\documentclass[12pt,oneside]{article}
\usepackage[utf8]{inputenc}
\usepackage{dcolumn,amsmath}

\begin{document}

The Ounk library contains two main kind of functions. The first one contains functions to write part of the csound file. This will defines the process chain to be compute by Csound. Another kind of functions are straigth Python functions. These functions serve to construct algorithmic musical patterns, manage Human Interface Device or build Graphical User Interface.

\chapter{Functions to write Csound file}

\section{Analysis}

A set of functions to analyse a given attribute of an audio input signal. Input signals are defined by setting the 'input' parameter. A control signal is sent by these functions and can be routed to any 'xxxVar' parameter by setting the 'bus' parameter.

\subsection{attackDetector}

Attack detector. Sends a trigger control signal on trigbus. 

\bigskip
{\bf SYNTAX}

attackDetector(input, trigbus, duration=None, starttime=0, lowpass=10, response=0.01, attackthresh=-6, minthresh=-50, releasethresh=0.4, releasetime=0.25)

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

trigbus : Name of the output control bus.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

lowpass : Cutoff, in hertz, of a lowpass filter applied on input signal.

response : Response time in seconds (attack time).

attackthresh : Attack threshold in dB. Trigger signal is send when rms amplitude of input signal exceed this threshold.

minthresh : Minimum dB level before detecting attack. rms amplitude of input signal must go down below this threshold to enable a new detection.

releasethresh : Release threshold, as fraction of attack rms amplitude.

releasetime : Release delay time, time to wait after signal have dropped below threshold.



* Based on an orchestra by Oeyvind Brandtsegg



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(-1)

inputMic(out='input', amplitude=.3)

attackDetector(input='input', trigbus='trig', attackthresh=-3, minthresh=-60)

tab = genRhythmTable()
pit = genDataTable([.5,.66,1,.75]*4)

metro(bus='met')

beginSequencer(input='met', table=tab, active=0, trigbus='trig', trigval=1)
sequencerPitchTable(pit)
pluckedString()
endSequencer()

startCsound()
\end{verbatim}

\subsection{centroid}

Follows the spectral centroid of a signal. Sends a control signal between 0 and 1 (1 == sr/2). 

\bigskip
{\bf SYNTAX}

centroid(input, bus, duration=None, starttime=0, fftsize=1024, overlaps=4, windowsize=2048)

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

bus : Name of the output control bus.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

fftsize : The FFT size in samples. Power of two are most efficient sizes. fftsize determines the number of analysis bins, as fftsize/2 + 1.

overlaps : Used to calculate the distance in samples (hop size) between overlapping analysis frames.

windowsize : The size in samples of the analysis window filter. This must be at least fftsize, and can usefully be larger.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(-1)

playSound('ounkmaster.aif', loop=True, out='snd')

centroid(input='snd', bus='cent')
waveform(pitch=20000, pitchVar='cent')

toDac(input='snd', amplitude=.3)

startCsound()
\end{verbatim}

\subsection{pitchAmp}

Follows the pitch and amplitude of a signal based on the AMDF (Average Magnitude Difference Function) method. Sends a transposition factor around the centralpitch on pitchbus and an amplitude factor normalized between 0 and 1 on ampbus.

\bigskip
{\bf SYNTAX}

pitchAmp(input, pitchbus, ampbus, duration=None, starttime=0, minfreq=50, maxfreq=500, pitchfilter=1, centralpitch=0, downsamp=1, rate=0)

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

pitchbus : Name of the output control bus for pitch value. Sends a transposition factor around the centralpitch.

ampbus : Name of the output control bus for amplitude value. Amplitude factor are normalized between 0 and 1.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

minfreq : Estimated minimum frequency (expressed in Hz) present in the signal.

maxfreq : Estimated maximum frequency present in the signal.

pitchfilter : Size of median filter applied to the output frequency estimation. The size of the filter will be imedi*2+1. If 0, no median filtering will be applied.

centralpitch : Pitch in Hz corresponding to a transposition factor of 1.

downsamp : Downsampling factor for input signal. Must be an integer. A factor of idowns > 1 results in faster performance, but may result in worse pitch detection. Useful range is 1 - 4.

rate : How frequently pitch analysis is executed, expressed in Hz. If 0, rate is set to minfreq.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
#### pitchAmp does not work with Csound 5.09 ###

from random import randint

setGlobalDuration(-1)

example = 1

playSound('ounkmaster.aif', loop=True, out='snd')

pitchAmp(input='snd', pitchbus='pit', ampbus='amp', maxfreq=600, centralpitch=100)
waveform(pitch=100, amplitude=.5, pitchVar='pit', amplitudeVar='amp')

toDac(input='snd', amplitude=.5)

startCsound()
\end{verbatim}

\subsection{rms}

Follows root-mean-square amplitude of a signal. Sends a control signal normalized between 0 and 1. 

\bigskip
{\bf SYNTAX}

rms(input, bus, duration=None, starttime=0, lowpass=10)

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

bus : Name of the output control bus.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

lowpass : Cutoff of a lowpass filter applied on input signal.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
playSound('ounkmaster.aif', loop=True, out='snd')
rms(input='snd', bus='rms')
freqMod(pitch=[52,99,153,205], modulator=[.49,.5,.51], index=10, amplitudeVar='rms')
toDac(input='snd', amplitude=.3)
startCsound()
\end{verbatim}



\section{Controls}

A set of functions to define control values that change over time. These functions send a control signal that can be routed to any 'xxxVar' parameter by setting the 'bus' parameter.

\subsection{busMix}

Mixes two bus controllers together by means of addition or multiplication.

\bigskip
{\bf SYNTAX}

busMix(bus, in1, in2, ftype='add', duration=None, starttime=0)

\bigskip
\subsection{busScale}

Adds and/or multiplies values to a bus controller.

\bigskip
{\bf SYNTAX}

busScale(bus, mult=1, add=0, duration=None, starttime=0)

\bigskip
\subsection{discreetTableLoop}

Loops over discreet values in a table with control on time between each picked values and step. 

\bigskip
{\bf SYNTAX}

discreetTableLoop(bus, table, speed=0.1, step=1, starttime=0, duration=None, reinittrigbus=None, speedVar=None, stepVar=None)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time, random

setGlobalDuration(20)

a = genDiscreetTable([3,4,5,6,7,8,9,10])

oscReceive(bus='init', address='/init', port=8000)

discreetTableLoop(bus='pit', table=a, speed=.125, reinittrigbus='init')

sine(pitch=100, pitchVar='pit', amplitude=.5)

proc = startCsound()

time.sleep(1)

def newPitches():
    pitches = random.sample([3,4,5,6,7,8,9,10], random.randint(2,8))
    reGenDiscreetTable(a, pitches, proc)

pat = pattern(time=2, function=newPitches)
pat.start()
pat.play()

def t():
    sendOscTrigger(value=1, address='/init')
\end{verbatim}

\subsection{expsegr}

Generates an exponential breakpoint envelope with a final release segment. Values must be non-zero and must agree in sign.

\bigskip
{\bf SYNTAX}

expsegr(bus, i1, dur1, i2, dur2=None, i3=None, dur3=None, i4=None, dur4=None, i5=None, final=0.0001, starttime=0, duration=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

i1 : Starting value of the curve.

dur1 : Duration, in seconds, of the first segment.

i2 : Second value of the curve.

dur2 : Duration, in seconds, of the second segment (optional).

i3 : Third value of the curve (optional).

dur3 : Duration, in seconds, of the third segment (optional).

i4 : Fourth value of the curve (optional).

dur4 : Duration, in seconds, of the fourth segment (optional).

i5 : Fifth value of the curve (optional).

final : Inside a MIDI instrument, curve will reach final value after the release of the note.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'. Sum of segment's dur must equal duration.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

expsegr(bus='amp', i1=.001, dur1=.5, i2=1, dur2=3, i3=.05, dur3=5, i4=.5, dur4=3.5, i5=.001)
expsegr(bus='ind', i1=1, dur1=1, i2=.3, dur2=11, i3=.1, )
freqMod(pitch=150, modulator=.505, index=15, amplitudeVar='amp', indexVar='ind')

startCsound()
\end{verbatim}

\subsection{jitter}

Generates a three stages jitter controller.

\bigskip
{\bf SYNTAX}

jitter(bus, amplitude=1, amp1=0.5, freq1=0.1, amp2=0.2, freq2=1, amp3=0.05, freq3=5, starttime=0, duration=None, amplitudeVar=None, amp1Var=None, freq1Var=None, amp2Var=None, freq2Var=None, amp3Var=None, freq3Var=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

amplitude : Resulting amplitude of jitter.

amp1 : Amplitude of the first jitter component.

freq1 : Speed of random variation of the first jitter component (expressed in cps).

amp2 : Amplitude of the second jitter component.

freq2 : Speed of random variation of the second jitter component (expressed in cps). 

amp3 : Amplitude of the third jitter component.

freq3 : Speed of random variation of the third jitter component (expressed in cps). 

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

amplitudeVar : Name of the control bus multiplying amplitude value.

amp1Var : Name of the control bus multiplying amp1 value.

freq1Var : Name of the control bus multiplying freq1 value.

amp2Var : Name of the control bus multiplying amp2 value.

freq2Var : Name of the control bus multiplying freq2 value.

amp3Var : Name of the control bus multiplying amp3 value.

freq3Var : Name of the control bus multiplying freq3 value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(30)

jitter(bus='jit', amplitude=1, amp1=.25, freq1=.1, amp2=.1, freq2=.5, amp3=.04, freq3=5)
sine(pitchVar='jit')

startCsound()
\end{verbatim}

\subsection{keyPressed}

Retreives the ASCII code of the key pressed on the keyboard and sends it on a controller bus.

\bigskip
{\bf SYNTAX}

keyPressed(bus, duration=None, starttime=0)

\bigskip
\subsection{lfo}

Generates a low frequency oscillator with different waveshapes.

\bigskip
{\bf SYNTAX}

lfo(bus, frequency=1, amplitude=1, wavetype='sine', offset=1, starttime=0, duration=None, frequencyVar=None, amplitudeVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

frequency : Frequency, in Hertz, of oscillator.

amplitude : Amplitude of oscillator.

wavetype : Determine the waveform of the oscillator, default to 'sine'. Possible wavetypes are 'sine', 'triangle', 'bisquare', 'unisquare', 'sawtooth', 'sawtoothdown'. 

offset : Value added to the output of the oscillator.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

frequencyVar : Name of the control bus multiplying frequency value.

amplitudeVar : Name of the control bus multiplying amplitude value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

env = genAdsr()

lfo(bus='amp', frequency=.5, amplitude=.5, offset=.5, wavetype='triangle')
lfo(bus='vib', frequency=5, amplitude=.05, offset=1, wavetype='sine')
square(pitch=100, envelope=env, pitchVar='vib', amplitudeVar='amp')

startCsound()
\end{verbatim}

\subsection{lfo2}

Generates a low frequency oscillator whose waveform is defined in a csound table, usually by using 'genWaveform' or 'genLineseg'.

\bigskip
{\bf SYNTAX}

lfo2(bus, frequency=1, amplitude=1, table='default', offset=1, starttime=0, duration=None, frequencyVar=None, amplitudeVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

frequency : Frequency, in Hertz, of oscillator.

amplitude : Amplitude of oscillator.

table : Table used as the waveform of the oscillator. Usually the value returned by 'genWaveform', 'genExpseg' or 'genLineseg'.

offset : Value added to the output of the oscillator.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

frequencyVar : Name of the control bus multiplying frequency value.

amplitudeVar : Name of the control bus multiplying amplitude value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

env = genAdsr()
amp = genLineseg([.001,10,1,10,.001])
vib = genWaveform([1,.5,.1,])

lfo2(bus='amp', frequency=.2, amplitude=1, offset=0, table=amp)
lfo2(bus='vib', frequency=5, amplitude=.05, offset=1, table=vib)
square(pitch=100, envelope=env, pitchVar='vib', amplitudeVar='amp')

startCsound()
\end{verbatim}

\subsection{linsegr}

Generates a breakpoint line with a final release segment

\bigskip
{\bf SYNTAX}

linsegr(bus, i1, dur1, i2, dur2=None, i3=None, dur3=None, i4=None, dur4=None, i5=None, final=0, starttime=0, duration=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

i1 : Starting value of the line.

dur1 : Duration, in seconds, of the first segment.

i2 : Second value of the line.

dur2 : Duration, in seconds, of the second segment (optional).

i3 : Third value of the line (optional).

dur3 : Duration, in seconds, of the third segment (optional).

i4 : Fourth value of the line (optional).

dur4 : Duration, in seconds, of the fourth segment (optional).

i5 : Fifth value of the line (optional).

final : Inside a MIDI instrument, line will reach final value after the release of the note.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'. Sum of segment's dur must equal duration.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

linsegr(bus='amp', i1=0, dur1=.5, i2=1, dur2=3, i3=.05, dur3=5, i4=.5, dur4=3.5, i5=0)
linsegr(bus='ind', i1=1, dur1=1, i2=.3, dur2=11, i3=.1, )
freqMod(pitch=150, modulator=.505, index=15, amplitudeVar='amp', indexVar='ind')

startCsound()
\end{verbatim}

\subsection{metro}

Defines and starts a metronome and sends it on a controller bus.

\bigskip
{\bf SYNTAX}

metro(bus, duration=None, starttime=0, tempo=120, tap=16, tapVar=None, tempoVar=None)

\bigskip
\subsection{midiCtl}

Takes a midi controller input and sends it on a controller bus.

\bigskip
{\bf SYNTAX}

midiCtl(bus, midichannel=1, ctlnumber=1, minscale=0, maxscale=127, duration=None, starttime=0)

\bigskip
\subsection{midiTrigger}

Sends a value on a controller bus when a midi controller is positive and immediatly after sends -1.

\bigskip
{\bf SYNTAX}

midiTrigger(bus, value=1, midichannel=1, ctlnumber=1, duration=None, starttime=0)

\bigskip
\subsection{midiTriggerInc}

Sends a value, starting at 1, on a controller bus when a midi controller is positive and immediatly after sends -1. The value is incremented by 1 until maxvalue is reached.

\bigskip
{\bf SYNTAX}

midiTriggerInc(bus, maxvalue=1, midichannel=1, ctlnumber=1, onevoice=True, duration=None, starttime=0)

\bigskip
\subsection{mouse}

Retreives the mouse position and sends it on a controller bus.

\bigskip
{\bf SYNTAX}

mouse(xbus, ybus, period=0.05, xmin=0, xmax=1, ymin=0, ymax=1, duration=None, starttime=0)

\bigskip
\subsection{oscReceive}

Receives data from an OSC port and sends it on  a controller bus.

\bigskip
{\bf SYNTAX}

oscReceive(bus, address, port, datatype='f', portamento=0, duration=None, starttime=0)

\bigskip
\subsection{oscSend}

Sends data on an OSC port.

\bigskip
{\bf SYNTAX}

oscSend(input, address, port, host='127.0.0.1', datatype='f', duration=None, starttime=0)

\bigskip
\subsection{oscTriggerSend}

Sends 1 at init on an OSC port and after sends 0's.

\bigskip
{\bf SYNTAX}

oscTriggerSend(address, port, host='127.0.0.1', datatype='f', duration=None, starttime=0)

\bigskip
\subsection{printMidiCtl}

Prints Midi controller info to the console without the need to startCsound().

\bigskip
{\bf SYNTAX}

printMidiCtl(duration=30)

\bigskip
\subsection{rando}

Generates random values at k-rate.

\bigskip
{\bf SYNTAX}

rando(bus, mini=0, maxi=1, starttime=0, duration=None, miniVar=None, maxiVar=None)

\bigskip
\subsection{randomChoice}

Chooses values randomly in a list and hold them.

\bigskip
{\bf SYNTAX}

randomChoice(bus, choice, rate=5, portamento=0, duration=None, starttime=0, rateVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

choice : List of values to choose from.

rate : Frequency, in Hertz, of random break-point generation.

portamento : Ramp time before control signal reaches a new value.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

rateVar : Name of the control bus multiplying rate value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(20)

env = genAdsr()
randomChoice(bus='pit1', choice=[.25,.5,.75,1,1.25,1.5,2], rate=1, portamento=.005)
randomChoice(bus='pit2', choice=[.25,.5,.75,1,1.25,1.5,2], rate=2, portamento=.005)
randomChoice(bus='pit3', choice=[.25,.5,.75,1,1.25,1.5,2], rate=4, portamento=.005)
sine(pitch=400, amplitude=.3, envelope=env, pitchVar='pit1')
sine(pitch=400, amplitude=.3, envelope=env, pitchVar='pit2')
sine(pitch=400, amplitude=.3, envelope=env, pitchVar='pit3')

startCsound()
\end{verbatim}

\subsection{randomh}

Generates random values and hold them.

\bigskip
{\bf SYNTAX}

randomh(bus, mini=0, maxi=1, rate=5, portamento=0, starttime=0, duration=None, miniVar=None, maxiVar=None, rateVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

mini : Minimum range limit.

maxi : Maximum range limit.

rate : Frequency, in Hertz, of random break-point generation.

portamento : Ramp time before control signal reaches a new value.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

miniVar : Name of the control bus multiplying mini value.

maxiVar : Name of the control bus multiplying maxi value.

rateVar : Name of the control bus multiplying rate value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

env = genAdsr()
randomh(bus='pit', mini=.75, maxi=2, rate=3, portamento=.005)
sine(pitch=300, envelope=env, pitchVar='pit')

startCsound()
\end{verbatim}

\subsection{randomi}

Generates random values with interpolation.

\bigskip
{\bf SYNTAX}

randomi(bus, mini=0, maxi=1, rate=5, starttime=0, duration=None, miniVar=None, maxiVar=None, rateVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

mini : Minimum range limit.

maxi : Maximum range limit.

rate : Frequency, in Hertz, of random break-point generation.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

miniVar : Name of the control bus multiplying mini value.

maxiVar : Name of the control bus multiplying maxi value.

rateVar : Name of the control bus multiplying rate value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

env = genAdsr()
randomi(bus='ind', mini=.1, maxi=1, rate=3)
freqMod(pitch=200, modulator=.501, index=10, envelope=env, indexVar='ind')

startCsound()
\end{verbatim}

\subsection{readTable}

Reads a controller table once over the whole duration of the function.

\bigskip
{\bf SYNTAX}

readTable(bus, table, starttime=0, duration=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

table : Table used as the envelope of the reader. Usually the value returned by a 'genXXX' function.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

env = genAdsr()
ind = genLineseg([1,8,.1,100,.3,100,.01])
readTable(bus='ind', table=ind)
freqMod(pitch=200, modulator=.501, index=10, envelope=env, indexVar='ind')

startCsound()
\end{verbatim}

\subsection{spline}

Generates random spline curves.

\bigskip
{\bf SYNTAX}

spline(bus, mini=0, maxi=1, minrate=5, maxrate=6, starttime=0, duration=None, miniVar=None, maxiVar=None, minrateVar=None, maxrateVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

mini : Minimum range limit.

maxi : Maximum range limit.

minrate : Minimum frequency, in Hertz, of point generation rate.

maxrate : Maximum frequency, in Hertz, of point generation rate.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

miniVar : Name of the control bus multiplying mini value.

maxiVar : Name of the control bus multiplying maxi value.

minrateVar : Name of the control bus multiplying minrate value.

maxrateVar : Name of the control bus multiplying maxrate value.



Real output range could be a bit greater of range values, because of interpolating curves beetween each pair of random-points. 



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

env = genAdsr()

spline(bus='spline', mini=.5, maxi=2, minrate=1, maxrate=5)
sine(pitch=500, pitchVar='spline', envelope=env)

startCsound()
\end{verbatim}

\subsection{trigEnvelope}

Reads a controller table, once on trigger signal, over the envdur duration.

\bigskip
{\bf SYNTAX}

trigEnvelope(bus, trigbus, table='default', envdur=1, starttime=0, duration=None)

\bigskip
\subsection{trigRandom}

Generates a new random value whenever receiving a trigger signal.

\bigskip
{\bf SYNTAX}

trigRandom(bus, trigbus, mini=0, maxi=1, starttime=0, duration=None, miniVar=None, maxiVar=None)

\bigskip
\subsection{vibrato}

Generates a vibrato controller.

\bigskip
{\bf SYNTAX}

vibrato(bus, frequency=5, amplitude=0.1, delay=0.5, slopedur=1, amplituderand=0.1, frequencyrand=0.2, ampminrate=1, ampmaxrate=3, freqminrate=1, freqmaxrate=3, starttime=0, duration=None, frequencyVar=None, amplitudeVar=None, amplituderandVar=None, frequencyrandVar=None, ampminrateVar=None, ampmaxrateVar=None, freqminrateVar=None, freqmaxrateVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

frequency : Average frequency value of vibrato (in hertz).

amplitude : Average amplitude value of vibrato.

delay : Delay, in seconds, before rising of the vibrato.

slopedur : Duration, in seconds, of the rising.

amplituderand : Amount of random amplitude deviation.

frequencyrand : Amount of random frequency deviation

ampminrate : Minimum frequency of random amplitude deviation segments (in hertz). 

ampmaxrate : Maximum frequency of random amplitude deviation segments (in hertz).

freqminrate : Minimum frequency of random frequency deviation segments (in hertz). 

freqmaxrate : Maximum frequency of random frequency deviation segments (in hertz).

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

frequencyVar : Name of the control bus multiplying frequency value.

amplitudeVar : Name of the control bus multiplying amplitude value.

amplituderandVar : Name of the control bus multiplying amplituderand value.

frequencyrandVar : Name of the control bus multiplying frequencyrand value.

ampminrateVar : Name of the control bus multiplying ampminrate value.

ampmaxrateVar : Name of the control bus multiplying ampmaxrate value.

freqminrateVar : Name of the control bus multiplying freqminrate value.

freqmaxrateVar : Name of the control bus multiplying freqmaxrate value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

vibrato(bus='vib', frequency=5.5, amplitude=.04, delay=1, slopedur=1.5)
sawtooth(pitch=100, pitchVar='vib', out='snd')
bandpass(input='snd', cutoff=500, bandwidth=80)
bandpass(input='snd', cutoff=1000, bandwidth=100)

startCsound()\end{verbatim}

\subsection{weightedRandomChoice}

Chooses randomly an element from a list, not uniformly, but using a given weight for each element, and hold them.

\bigskip
{\bf SYNTAX}

weightedRandomChoice(bus, choice, rate=5, portamento=0, duration=None, starttime=0, rateVar=None)

\bigskip
{\bf PARAMETERS}





bus : Name of the output control bus.

choice : List of tuples containing value to choose and their weight. This parameter can't be a list of list!

rate : Frequency, in Hertz, of random break-point generation.

portamento : Ramp time before control signal reaches a new value.

starttime : Starting time of the function performance in seconds.

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

rateVar : Name of the control bus multiplying rate value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(30)

weightedRandomChoice(bus=['pit1','pit2'], choice=[(250,20), (333,10), (500,200), (666,10), (750,50), (1000,20)], rate=[15,15])

sine(pitch=[1,.995], amplitude=.5, pitchVar=['pit1','pit2'])

startCsound()
\end{verbatim}



\section{Custom Inst}

This set of functions allows the user to import a csound instrument from a text file for use inside the Ounk framework.

\subsection{myInstrument}

Define a custom csound instrument.

\bigskip
{\bf SYNTAX}

myInstrument(file='', starttime=0, duration=None, pan=0.5, argslist=[], vardict={}, nosound=False, out='dac')

\bigskip


\section{Effects}

A set of functions that take audio samples as input, as defined by the 'input' parameter, and applies signal processing functions to them. Routing is done by setting the 'out' parameter.

\subsection{compressor}

Compress or expand an audio signal.

\bigskip
{\bf SYNTAX}

compressor(input, threshold=-30, amplitude=1, duration=None, starttime=0, lowfactor=1, highfactor=0.5, risetime=0.1, falltime=0.1, pan=0.5, thresholdVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{delay}

Delays an input signal by some time interval.

\bigskip
{\bf SYNTAX}

delay(input, amplitude=1, duration=None, starttime=0, delaytime=1, pan=0.5, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

delaytime : Requested delay time in seconds. 

pan : Position value between 0 and 1.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

playSound(sound = 'ounkmaster.aif', out = 'snd')
toDac(input = 'snd')
delay(input = 'snd', delaytime = .5)

startCsound()
\end{verbatim}

\subsection{didjeridu}

Emulate a didjeridu (lips vibration + truncated cone). Input audio signal is modulated by lip vibrations before passing into a bank of resonators.

\bigskip
{\bf SYNTAX}

didjeridu(input, pitch=75, amplitude=1, duration=None, starttime=0, drone=1, length=1.5, pressure=0.9, formant=500, resonances=20, pan=0.5, pitchVar=None, droneVar=None, lengthVar=None, pressureVar=None, formantVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{distortion}

Apply distortion to the audio signal.

\bigskip
{\bf SYNTAX}

distortion(input, amplitude=1, duration=None, starttime=0, drive=0.75, cutoff=6000, pan=0.5, driveVar=None, cutoffVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

drive : Amount of distortion (usually between 0 and 1).

cutoff : Cutoff frequency of the lowpass filter applied on distortion output. 

pan : Position value between 0 and 1.

driveVar : Name of the control bus multiplying drive value.

cutoffVar : Name of the control bus multiplying cutoff value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

env = genAdsr()
sawtooth(pitch=150, envelope=env, out='saw')

lfo(bus='drv', amplitude=.5, offset=.5)
distortion(input='saw', drive=.999, cutoff=6000, driveVar='drv')

startCsound()\end{verbatim}

\subsection{flanger}

Generates harmonizing voices based on the audio signal.

\bigskip
{\bf SYNTAX}

flanger(input, delay=0.005, amplitude=1, duration=None, starttime=0, lfofreq=0.1, lfoamp=0.002, feedback=0.5, pan=0.5, delayVar=None, lfofreqVar=None, lfoampVar=None, feedbackVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

delay : Average delay in seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

lfofreq : Frequency of the low frequency oscillator modulating the delay.

lfoamp : Amplitude of the low frequency oscillator modulating the delay. Must be lower than delay / 2.

feedback : Amount of signal reinjected in the loop (between -1 and 1).

pan : Position value between 0 and 1.

delayVar : Name of the control bus multiplying delay value.

lfofreqVar : Name of the control bus multiplying lfofreq value.

lfoampVar : Name of the control bus multiplying lfoamp value.

feedbackVar : Name of the control bus multiplying feedback value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
pinkNoise(amplitude=.5, out='s')

flanger(input='s', delay=.005, lfoamp=.002, lfofreq=.1, feedback=.5)

startCsound()
\end{verbatim}

\subsection{fold}

Adds artificial foldover to an audio signal.

\bigskip
{\bf SYNTAX}

fold(input, amplitude=1, duration=None, starttime=0, amount=0, pan=0.5, amountVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{harmonizer}

Generates harmonizing voices based on the audio signal.

\bigskip
{\bf SYNTAX}

harmonizer(input, transpo=7, amplitude=1, duration=None, starttime=0, winsize=64, feedback=0, mix=0.5, pan=0.5, transpoVar=None, winsizeVar=None, feedbackVar=None, mixVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

transpo : Amount of transposition in semitones.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

winsize : Length of window, in milliseconds.

feedback : Amount of signal reinjected in the loop (between -1 and 1).

mix : Amplitude of transposed sound vs input sound at the output.

pan : Position value between 0 and 1.

transpoVar : Name of the control bus multiplying transpo value.

winsizeVar : Name of the control bus multiplying winsize value.

feedbackVar : Name of the control bus multiplying feedback value.

mixVar : Name of the control bus multiplying mix value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

playSound(sound = 'ounkmaster.aif', out = 'snd')

harmonizer(input = 'snd', transpo = -12, delay = 1, feedback = .5)

startCsound()\end{verbatim}

\subsection{phaser}

Sound is passed through second-order allpass filters arranged in a series.

\bigskip
{\bf SYNTAX}

phaser(input, pitch=100, amplitude=1, duration=None, starttime=0, q=0.5, feedback=0.5, scale=1, order=10, mode=1, pan=0.5, pitchVar=None, qVar=None, feedbackVar=None, scaleVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

pitch : This is the center frequency of the notch of the first allpass filter in the series. This frequency is used as the base frequency from which the frequencies of the other notches are derived.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

q : Q of each notch. Higher Q values result in narrow notches.

feedback : Amount of signal reinjected in the allpass chain (between -1 and 1).

scale : Scaling factor used, in conjunction with imode, to determine the frequencies of the additional notches in the output spectrum. 

order : Number of allpass stages in series. 

mode : Used in calculation of notch frequencies. When mode = 1, notches are in harmonic relationship. When mode = 2, notches are in octave relationship.  

pan : Position value between 0 and 1.

pitchVar : Name of the control bus multiplying pitch value.

qVar : Name of the control bus multiplying q value.

feedbackVar : Name of the control bus multiplying feedback value.

scaleVar : Name of the control bus multiplying scale value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
pinkNoise(amplitude=.5, out='s')

lfo(bus='pit', amplitude=.25, frequency=.1)

phaser(input='s', pitch=100, q=.5, feedback=.75, scale=1, order=25, mode=1, pitchVar='pit')

startCsound()
\end{verbatim}

\subsection{resonator}

Audio signal is passed through a resonator.

\bigskip
{\bf SYNTAX}

resonator(input, pitch=100, amplitude=1, duration=None, starttime=0, cutoff=6000, feedback=0.99, pan=0.5, pitchVar=None, cutoffVar=None, feedbackVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

pitch : Frequency (i.e. the inverse of delay time), in Hertz, of the resonator.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Frequency, in Hertz, of a lowpass filter inside the loop.

feedback : Amount of signal reinjected in the loop (between -1 and 1).

pan : Position value between 0 and 1.

pitchVar : Name of the control bus multiplying pitch value.

cutoffVar : Name of the control bus multiplying cutoff value.

feedbackVar : Name of the control bus multiplying feedback value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

playSound(sound = 'ounkmaster.aif', out = 'snd')

linsegr(bus = 'amp', i1 = 1, dur1 = 11, i2 = 1, dur2 = 1, i3 = 0)
resonator(input = 'snd', pitch = 100, feedback = .999, cutoff = 1500, amplitudeVar = 'amp')

startCsound()
\end{verbatim}

\subsection{ringMod}

Perform ring modulation on the audio signal.

\bigskip
{\bf SYNTAX}

ringMod(in1, in2, amplitude=1, duration=None, starttime=0, pan=0.5, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{vdelay}

Audio signal is passed through an interpolating variable time delay with feedback.

\bigskip
{\bf SYNTAX}

vdelay(input, delay=1, amplitude=1, duration=None, starttime=0, feedback=0.5, pan=0.5, delayVar=None, feedbackVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

delay : Delay in seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

feedback : Amount of signal reinjected in the loop (between -1 and 1).

pan : Position value between 0 and 1.

delayVar : Name of the control bus multiplying delay value.

feedbackVar : Name of the control bus multiplying feedback value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\subsection{vocoder}

Applies the analysed spectral envelope of a sound to an excitation signal.

\bigskip
{\bf SYNTAX}

vocoder(in1, in2, amplitude=1, duration=None, starttime=0, minfreq=200, maxfreq=5000, q=20, bands=32, pan=0.5, minfreqVar=None, maxfreqVar=None, qVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
train(pitch=100, amplitude=0.5, out='excite')
pinkNoise(amplitude=0.5, out='excite')

playSound(loop=True, out='anal')

vocoder(in1='excite', in2='anal', minfreq=200, maxfreq=5000, q=5, bands=20)

startCsound()
\end{verbatim}



\section{Filters}

A set of functions that take audio samples as input, as defined by the 'input' parameter, and applies filtering to them. Routing is done by setting the 'out' parameter.

\subsection{bandpass}

Filter the audio signal with a butterworth bandpass filter.

\bigskip
{\bf SYNTAX}

bandpass(input, amplitude=1, duration=None, starttime=0, cutoff=6000, bandwidth=1000, pan=0.5, cutoffVar=None, bandwidthVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Center frequency, in Hertz, of the filter. 

bandwidth : Bandwidth, in Hertz,  of the filter.

pan : Position value between 0 and 1.

cutoffVar : Name of the control bus multiplying cutoff value.

bandwidthVar : Name of the control bus multiplying bandwidth value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

pinkNoise(amplitude=1, out='noise')

expsegr(bus='fvar', i1=1, dur1=10, i2=.05)
bandpass(input='noise', cutoff=5000, bandwidth=500, cutoffVar='fvar', bandwidthVar='fvar')

startCsound()\end{verbatim}

\subsection{bandreject}

Filter the audio signal with a butterworth bandreject filter.

\bigskip
{\bf SYNTAX}

bandreject(input, amplitude=1, duration=None, starttime=0, cutoff=6000, bandwidth=1000, pan=0.5, cutoffVar=None, bandwidthVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Center frequency, in Hertz, of the filter. 

bandwidth : Bandwidth, in Hertz,  of the filter.

pan : Position value between 0 and 1.

cutoffVar : Name of the control bus multiplying cutoff value.

bandwidthVar : Name of the control bus multiplying bandwidth value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

pinkNoise(out='noise')

lfo(bus='fvar', amplitude=.5, offset=1)
bandreject(input='noise', cutoff=5000, bandwidth=1000, cutoffVar='fvar', bandwidthVar='fvar')

startCsound()
\end{verbatim}

\subsection{dcblock}

A DC blocking filter.

\bigskip
{\bf SYNTAX}

dcblock(input, amplitude=1, duration=None, starttime=0, pan=0.5, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{eqFilter}

Peaking, low shelving or high shelving filter.

\bigskip
{\bf SYNTAX}

eqFilter(input, amplitude=1, duration=None, starttime=0, cutoff=6000, boost=1, q=0.707, mode=0, pan=0.5, cutoffVar=None, boostVar=None, qVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{highpass}

Filter the audio signal with a butterworth highpass filter.

\bigskip
{\bf SYNTAX}

highpass(input, amplitude=1, duration=None, starttime=0, cutoff=6000, pan=0.5, cutoffVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Cutoff frequency, in Hertz, of the filter. 

pan : Position value between 0 and 1.

cutoffVar : Name of the control bus multiplying cutoff value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

playSound(sound='ounkmaster.aif', out='snd')
highpass(input='snd', amplitude=2, cutoff=3000)

startCsound()\end{verbatim}

\subsection{lowpass}

Filter the audio signal with a butterworth lowpass filter.

\bigskip
{\bf SYNTAX}

lowpass(input, amplitude=1, duration=None, starttime=0, cutoff=6000, pan=0.5, cutoffVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Cutoff frequency, in Hertz, of the filter. 

pan : Position value between 0 and 1.

cutoffVar : Name of the control bus multiplying cutoff value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

playSound(sound='ounkmaster.aif', out='snd')
lowpass(input='snd', amplitude=2, cutoff=300)

startCsound()\end{verbatim}

\subsection{resFilter}

Filter the audio signal with a second-order multi-mode filter.

\bigskip
{\bf SYNTAX}

resFilter(input, amplitude=1, duration=None, starttime=0, cutoff=6000, resonance=1, mode=0, pan=0.5, cutoffVar=None, resonanceVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip


\section{GenTables}

This set of functions create and fill Csound tables. Csound tables are memory buffers containing sound samples, discrete data values, waveforms, envelopes, etc. Functions return the csound table number, which can be assigned to a 'table' parameter.

\subsection{genAdsr}

Defines an ADSR envelope. Returns table number.

\bigskip
{\bf SYNTAX}

genAdsr(attack=0.01, decay=0.1, sustain=0.8, release=0.1, size=8192)

\bigskip
{\bf PARAMETERS}





attack : Duration of attack phase.

decay : Duration of decay.

sustain : Amplitude for sustain phase.

release : Duration of release phase.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.



The envelope is in the range 0 to 1.



attack, decay, and release are fractional parts of the table size (where table size == 1). The length of the sustain is calculated from the unused part of table size.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(5)

env = genAdsr(attack=.05, decay=.1, sustain=.7, release=.2)
freqMod(pitch=250, modulator=.501, envelope=env)

startCsound()
\end{verbatim}

\subsection{genDataFileTable}

Writes data in a file and loads it in a table. The first position in the generated table will be the number of elements in the list. 

\bigskip
{\bf SYNTAX}

genDataFileTable(list)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time, random

setGlobalDuration(20)

pitches = [random.randint(50,100) for i in range(1000)]

a = genDataFileTable(pitches)

oscReceive(bus='init', address='/init', port=8000)

discreetTableLoop(bus='pit', table=a, speed=.06125, reinittrigbus='init')

sine(pitch=10, pitchVar='pit', amplitude=.5)

proc = startCsound()

time.sleep(1)

def newPitches():
    pitches = [random.randint(100,200) for i in range(15000)]
    reGenDataFileTable(a, pitches, proc)

pat = pattern(time=2, function=newPitches)
pat.start()
pat.play()

def t():
    sendOscTrigger(value=1, address='/init')
\end{verbatim}

\subsection{genDataTable}

Generates a table filled with a list of discrete values. Can be a list of sound name as strings. Returns table number.

\bigskip
{\bf SYNTAX}

genDataTable(list)

\bigskip
\subsection{genDiscreetTable}

Generates a table filled with a list of discrete values. The first position in the generated table will be the number of elements in the list. 

\bigskip
{\bf SYNTAX}

genDiscreetTable(list)

\bigskip
\subsection{genExpseg}

Defines an exponential breakpoints envelope. Returns table number.

\bigskip
{\bf SYNTAX}

genExpseg(list=[0.001, 10, 1, 10, 0.001, 10, 1, 10, 0.001], size=8192)

\bigskip
{\bf PARAMETERS}





list : list begins with start value of the function and is followed by any pair (duration, value). Values must be non-zero. Durations are rescaled to fit table size.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(5)

env = genExpseg([.001,10,1,100,.7,100,.001])
ind = genExpseg([1,40,.1,100,.3,100,.1])
readTable(bus='ind', table=ind)
freqMod(pitch=250, modulator=.501, index=20, envelope=env, indexVar='ind')

startCsound()
\end{verbatim}

\subsection{genLineseg}

Defines a breakpoints envelope. Returns table number.

\bigskip
{\bf SYNTAX}

genLineseg(list=[0, 10, 1, 10, 0, 10, 1, 10, 0], size=8192)

\bigskip
{\bf PARAMETERS}





list : list begins with start value of the function and is followed by any pair (duration, value). Durations are rescaled to fit table size.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

env = genLineseg([0,10,1,100,1,10,0])
mod = genLineseg([1,40,.9,100,1.02,100,.95,200,1.1,100,1])
readTable(bus='mod', table=mod)
freqMod(pitch=250, modulator=.501, index=10, envelope=env, modulatorVar='mod')

startCsound()
\end{verbatim}

\subsection{genPulsarWave}

Loads a waveform in a table. Returns table number.

\bigskip
{\bf SYNTAX}

genPulsarWave(sound)

\bigskip
\subsection{genRhythmTable}

Generates a rhythm taps table for use with the sequencer. Returns table number.

\bigskip
{\bf SYNTAX}

genRhythmTable(size=16, weight1=90, weight2=60, weight3=20)

\bigskip
\subsection{genSoundTable}

Loads a soundfile in a table. Returns table number.

\bigskip
{\bf SYNTAX}

genSoundTable(sound, skiptime=0)

\bigskip
\subsection{genWaveform}

Defines a complex waveform to be read by a complex function. Returns table number.

\bigskip
{\bf SYNTAX}

genWaveform(list=[1, 0, 0, 0.29999999999999999, 0, 0.20000000000000001, 0, 0, 0.10000000000000001], size=8192)

\bigskip
{\bf PARAMETERS}





list : Relative strengths of the fixed harmonic partial numbers 1,2,3, etc. Partials not required should be given a strength of zero.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(5)

env = genAdsr()
onde = genWaveform([1,0,0,.3,0,0,.2,0,0,.1,0,0,.05])
waveform(pitch=250, table=onde, envelope=env)

startCsound()
\end{verbatim}

\subsection{genWindow}

Defines window function. Returns table number.

\bigskip
{\bf SYNTAX}

genWindow(choice='hanning', size=8192)

\bigskip
{\bf PARAMETERS}





choice : Type of window to generate. Possible choices are 'hamming', 'hanning', 'bartlett', 'blackman', 'blackman-harris', 'gaussian'.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.



The envelope is in the range 0 to 1.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(5)

env = genWindow(choice='hanning')
freqMod(pitch=250, modulator=.501, envelope=env)

startCsound()
\end{verbatim}

\subsection{reGenAdsr}

Modifies an existing ADSR envelope table.

\bigskip
{\bf SYNTAX}

reGenAdsr(table, attack=0.01, decay=0.1, sustain=0.8, release=0.1, size=8192, process=1)

\bigskip
{\bf PARAMETERS}





table : Number returned by genAdsr function specifying table to modify.

attack : Duration of attack phase.

decay : Duration of decay.

sustain : Amplitude for sustain phase.

release : Duration of release phase.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.

process : Ounk process number of the script, returned by startCsound.



The envelope is in the range 0 to 1.



attack, decay, and release are fractional parts of the table size (where table size == 1). The length of the sustain is calculated from the unused part of table size.



\subsection{reGenDataFileTable}

Modifies an existing data file ftable.

\bigskip
{\bf SYNTAX}

reGenDataFileTable(table, list, process=1)

\bigskip
\subsection{reGenDataTable}

Modifies an existing data ftable.

\bigskip
{\bf SYNTAX}

reGenDataTable(table, list, process=1)

\bigskip
\subsection{reGenDiscreetTable}

Modifies an existing discreet data ftable.

\bigskip
{\bf SYNTAX}

reGenDiscreetTable(table, list, process=1)

\bigskip
\subsection{reGenExpseg}

Modifies an existing exponential breakpoints envelope.

\bigskip
{\bf SYNTAX}

reGenExpseg(table, list, size=8192, process=1)

\bigskip
{\bf PARAMETERS}





table : Number returned by genExpseg function specifying table to modify.

list : list begins with start value of the function and is followed by any pair (duration, value). Values must be non-zero. Durations are rescaled to fit table size.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.

process : Ounk process number of the script, returned by startCsound.



\subsection{reGenLineseg}

Modifies an existing breakpoints envelope.

\bigskip
{\bf SYNTAX}

reGenLineseg(table, list, size=8192, process=1)

\bigskip
{\bf PARAMETERS}





table : Number returned by genLineseg function specifying table to modify.

list : list begins with start value of the function and is followed by any pair (duration, value). Durations are rescaled to fit table size.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.

process : Ounk process number of the script, returned by startCsound.



\subsection{reGenSoundTable}

Modifies an existing soundfile table.

\bigskip
{\bf SYNTAX}

reGenSoundTable(table, sound, skiptime=0, process=1)

\bigskip
\subsection{reGenWaveform}

Modifies an existing waveform ftable.

\bigskip
{\bf SYNTAX}

reGenWaveform(table, list, size=8192, process=1)

\bigskip
\subsection{reGenWindow}

Modifies an existing window function table.

\bigskip
{\bf SYNTAX}

reGenWindow(table, choice='hanning', size=8192, process=1)

\bigskip
{\bf PARAMETERS}





table : Number returned by genWindow function specifying table to modify.

choice : Type of window to generate. Possible choices are 'hamming', 'hanning', 'bartlett', 'blackman', 'blackman-harris', 'gaussian'.

size : Number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1. The maximum tablesize is 16777216 (2^24) points.

process : Ounk process number of the script, returned by startCsound.



The envelope is in the range 0 to 1.



\subsection{recordBuffer}

Creates an empty buffer and record 'bufferlength' seconds of audio signal on trigger signal.

\bigskip
{\bf SYNTAX}

recordBuffer(input, trigbus, bufferlength=1, starttime=0, duration=None)

\bigskip
\subsection{tableMorphing}

Performs morphing between two or more discrete value tables. Returns table number.

\bigskip
{\bf SYNTAX}

tableMorphing(tablelist, indexVar=0, length=8192, starttime=0, duration=None)

\bigskip


\section{General}

Set of functions to customize the environment, ie: path management, audio attributes and global durations.

\subsection{clear}

Clears global variables.

\bigskip
{\bf SYNTAX}

clear()

\bigskip
\subsection{getAudioAttributes}

Prints audio attributes to the console.

\bigskip
{\bf SYNTAX}

getAudioAttributes()

\bigskip
\subsection{getImpulsePath}

Prints impulse path to the console and returns it.

\bigskip
{\bf SYNTAX}

getImpulsePath()

\bigskip
\subsection{getMidiPath}

Prints midi path to the console and returns it.

\bigskip
{\bf SYNTAX}

getMidiPath()

\bigskip
\subsection{getSoundInfo}

Retrieves information of the sound and prints it to the console.

\bigskip
{\bf SYNTAX}

getSoundInfo(sound)

\bigskip
\subsection{getSoundList}

Prints sounds list to the console and returns it.

\bigskip
{\bf SYNTAX}

getSoundList()

\bigskip
\subsection{getSoundPath}

Prints the sound path to the console and returns it

\bigskip
{\bf SYNTAX}

getSoundPath()

\bigskip
\subsection{getSoundfontPath}

Prints the soundfont path to the console and returns it

\bigskip
{\bf SYNTAX}

getSoundfontPath()

\bigskip
\subsection{onStop}

This fonction is called when a script has finished its performance. Can be overriden to call some processes just at the end of a performance. Only work with Ounk GUI.

\bigskip
{\bf SYNTAX}

onStop()

\bigskip
\subsection{setAudioAttributes}

Sets audio attributes.

\bigskip
{\bf SYNTAX}

setAudioAttributes(samplingrate=None, controlrate=None, softbuffer=None, hardbuffer=None, sampleformat=None, audioformat=None, audiodriver=None)

\bigskip
\subsection{setAudioDevice}

Sets the input number of the desired Audio device. See the Csound log to know which devices connected. If None Csound will try its default value.

\bigskip
{\bf SYNTAX}

setAudioDevice(inumber=None, onumber=None)

\bigskip
\subsection{setChannels}

Changes the number of channels used by functions to set inputs and outputs. Can be used any number of times in a script.

\bigskip
{\bf SYNTAX}

setChannels(channels=2)

\bigskip
\subsection{setGlobalDuration}

Sets the global duration. If a function duration is None, the global duration is used.

\bigskip
{\bf SYNTAX}

setGlobalDuration(dur)

\bigskip
{\bf PARAMETERS}





dur : Global duration of the script in seconds.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(16)

# will play for 12 seconds
playSound(sound='ounkmaster.aif', duration=12, out='snd')

# will play for duration specified by setGlobalDuration
reverb(input='snd', mix=.3)

startCsound()
\end{verbatim}

\subsection{setImpulsePath}

Sets path of the impulse response files folder.

\bigskip
{\bf SYNTAX}

setImpulsePath(path)

\bigskip
\subsection{setMidiDevice}

Sets the input number of the desired Midi device. See the Csound log to know which devices connected.

\bigskip
{\bf SYNTAX}

setMidiDevice(number)

\bigskip
\subsection{setMidiPath}

Sets the path to the midi folder.

\bigskip
{\bf SYNTAX}

setMidiPath(path)

\bigskip
\subsection{setSoundPath}

Sets the path to the audio file folder.

\bigskip
{\bf SYNTAX}

setSoundPath(path)

\bigskip
\subsection{setSoundfontPath}

Sets the path to the soundfonts folder.

\bigskip
{\bf SYNTAX}

setSoundfontPath(path)

\bigskip
\subsection{speakersConfig}

Changes the order of output numbers. Number of arguments must fit number of used outputs. Speaker numbers begin at 0.

\bigskip
{\bf SYNTAX}

speakersConfig()

\bigskip


\section{Loops}

A set of functions to create note loops, providing control on note amplitude and duration over the full duration of the loop.

\subsection{beginLoop}

Starts the definition of a looping section.

\bigskip
{\bf SYNTAX}

beginLoop(starttime=0, duration=None, legato=None, amplitude=None)

\bigskip
\subsection{endLoop}

Closes the loop section.

\bigskip
{\bf SYNTAX}

endLoop()

\bigskip


\section{Midi Synth}

A set of functions to build MIDI synthesizers. Every process between function flags 'beginMidiSynth' and 'endMidiSynth' will respond to noteon and noteoff triggers. Routing of audio samples and controller values inside a Midi Synth are valid only for the synthesizer. Routing of the synthesizer sound can be done by setting the 'out' parameter of the 'endMidiSynth' function.

\subsection{beginMidiSynth}

Begins the definition of a MIDI instrument.

\bigskip
{\bf SYNTAX}

beginMidiSynth(channel=1, centralkey=60, release=1, pitchbend=2, skipampscaling=False)

\bigskip
\subsection{endMidiSynth}

Closes the definition of a MIDI instrument.

\bigskip
{\bf SYNTAX}

endMidiSynth(out='dac')

\bigskip
\subsection{midiSynthCtl}

Takes a midi controller as input and sends it on a controller bus.

\bigskip
{\bf SYNTAX}

midiSynthCtl(bus, ctlnumber=1, minscale=0, maxscale=127, portamento=0.02)

\bigskip
\subsection{midiSynthGetBus}

Retrieves an external controller to use in a MIDI instrument.

\bigskip
{\bf SYNTAX}

midiSynthGetBus(bus, input)

\bigskip
\subsection{readMidiFile}

Reads a midi file.

\bigskip
{\bf SYNTAX}

readMidiFile(file)

\bigskip
\subsection{splitKeyboard}

Defines a keyboard region in a MIDI instrument.

\bigskip
{\bf SYNTAX}

splitKeyboard(firstnote=0, endnote=127, centralkey=48, pitchbend=2)

\bigskip
\subsection{splitVelocity}

Defines a velocity region in a MIDI instrument.

\bigskip
{\bf SYNTAX}

splitVelocity(minthresh=0, maxthresh=1)

\bigskip


\section{Output}

Management of Csound. Start, stop, recording, management of multiple processes, etc.

\subsection{createLadspaPlugin}

Ounk will create a ladspa plugin instead of playing sound. controlDict defines real-time controlers of the plugin.

\bigskip
{\bf SYNTAX}

createLadspaPlugin(pluginname='Ounk plugin', controldict={})

\bigskip
\subsection{directOut}

Audio signals in input are routed to dac with an offset on physical outputs.

\bigskip
{\bf SYNTAX}

directOut(input, amplitude=1, duration=None, starttime=0, offset=0, amplitudeVar=None)

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

offset : Output where to send the first audio channel in input. Give the number of the physical output starting at 0. Can't be a list.

amplitudeVar : Name of the control bus multiplying amplitude value.



\subsection{getPid}

Returns the csound process id.

\bigskip
{\bf SYNTAX}

getPid(num=None)

\bigskip
\subsection{monitor}

Monitors the global linear amplitude at the output of Csound and sends it normalized between 0 and 1 on an OSC port.

\bigskip
{\bf SYNTAX}

monitor(host='127.0.0.1', port=15001, address='/monitor')

\bigskip
\subsection{recordPerf}

Records the performance.

\bigskip
{\bf SYNTAX}

recordPerf(name='perf', duration=None)

\bigskip
\subsection{route}

Audio signals in input are routed to out.

\bigskip
{\bf SYNTAX}

route(input, amplitude=1, duration=None, starttime=0, pan=0.5, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(15)

playSound(sound='ounkmaster.aif', out='snd')
# dry 'snd' are routed to reverb and to the delay line 
route(input='snd', out='rev')
delay(input='snd', delaytime=.5, out='rev')
reverb(input='rev', revtime=1, mix=.25)

startCsound()
\end{verbatim}

\subsection{startCsound}

Compiles a .csd file and starts csound with it. If a string is given as a second argument, it writes a file on disk instead of sending sound to speakers.

\bigskip
{\bf SYNTAX}

startCsound(duration=None, file=None, channels=None, amplitude=1, nosound=False)

\bigskip
{\bf PARAMETERS}





duration : Duration of the function performance in seconds. Uses global duration if 'None'.

file : If a string is given, Csound will write a file on disk instead of sending sound to speakers. Extension (.aif or .wav), defined by 'audioFormat', will be added to filename. Sounds will be saved in prefered snds folder.

channels : Forces the number of Csound audio output channels.

amplitude : Adjust the overall amplitude of the performance.

nosound : If this parameter is True, no sound will be send to dac (digital to analog converter).



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(15)

playSound(sound='ounkmaster.aif')

# Sends sound to speakers
startCsound()

# Writes a file on disk
#startCsound(file='sound')

# Forces number of channels
#startCsound(file='quad', channels=4)\end{verbatim}

\subsection{stopCsound}

Stops the current csound instance and running processes.

\bigskip
{\bf SYNTAX}

stopCsound(num=None)

\bigskip
\subsection{toDac}

Audio signals in input are routed to dac.

\bigskip
{\bf SYNTAX}

toDac(input, amplitude=1, duration=None, starttime=0, pan=0.5, amplitudeVar=None, panVar=None)

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(15)

playSound(sound='ounkmaster.aif', out='snd')
# dry 'snd' are routed to speakers and to the delay line 
toDac(input='snd')
delay(input='snd', delaytime=.5)

startCsound()
\end{verbatim}

\subsection{udpAudioReceive}

Receives audio signal from a UPD port.

\bigskip
{\bf SYNTAX}

udpAudioReceive(port=9000, duration=None, starttime=0, out='dac')

\bigskip
\subsection{udpAudioSend}

Sends audio signal on a UPD port.

\bigskip
{\bf SYNTAX}

udpAudioSend(input, port=9000, host='127.0.0.1', duration=None, starttime=0)

\bigskip


\section{Python Inst}

This set of functions create an instrument that waits for events from Csound stdin ('sendEvent' is the function to send an event to the Csound stdin). All function parameters in the instrument can be modified by passing a dictionary of parameters to 'sendEvent'.

\subsection{beginPythonInst}

Begins the definition of a Python instrument.

\bigskip
{\bf SYNTAX}

beginPythonInst(voice=1)

\bigskip
{\bf PARAMETERS}





voice : The number of the instrument as an arbitrary number. This value can be used to send events to this particular instrument with sendEvent function.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(15)

beginPythonInst(voice=1)
playSound()
endPythonInst()

proc = startCsound()


time.sleep(1)
sendEvent(voice=1, dict={}, process=proc)
time.sleep(3)
sendEvent(voice=1, dict={}, process=proc)
\end{verbatim}

\subsection{endPythonInst}

Closes the python instrument section.

\bigskip
{\bf SYNTAX}

endPythonInst()

\bigskip
{\bf PARAMETERS}





No parameter. This function closes the definition of a Python instrument.

    

\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(15)

beginPythonInst(voice=1)
playSound()
endPythonInst()

proc = startCsound()


time.sleep(1)
sendEvent(voice=1, dict={}, process=proc)
time.sleep(3)
sendEvent(voice=1, dict={}, process=proc)
\end{verbatim}



\section{Reverbs}

A set of functions that take audio samples as input, as defined by the 'input' parameter, and applies reverberation to them. Routing is done by setting the 'out' parameter.

\subsection{convolveReverb}

Apply convolution reverb to the audio signal.

\bigskip
{\bf SYNTAX}

convolveReverb(input, impulse='ORTFFloorR10.wav', amplitude=1, mix=0.1, buffersize=512, duration=None, starttime=0, pan=0.5, amplitudeVar=None, mixVar=None, panVar=None, out='dac')

\bigskip
\subsection{infiniteReverb}

Each time a trigger is detected on trigbus, a little snapshot of sound in input is infinitely reverberated. A trigger on clearbus clears reverb memory.

\bigskip
{\bf SYNTAX}

infiniteReverb(input, trigbus, clearbus, amplitude=1, duration=None, starttime=0, cutoff=10000, pan=0.5, cutoffVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

trigbus : Name of the controller bus waiting for a trigger signal.

clearbus : Name of the controller bus waiting for a trigger signal to clear reverb memory.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Cutoff frequency of simple first order lowpass filters in the feedback loop of delay lines, in Hz.

pan : Position value between 0 and 1.

cutoffVar : Name of the control bus multiplying cutoff value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(-1)

randomh(bus='pit', mini=.5, maxi=2, rate=.5)

sine(amplitude=.5, pitchVar='pit', out='s')

oscReceive(bus=['trig', 'clear'], address=['/trig', '/clear'], port=8000)

infiniteReverb(input='s', trigbus='trig', clearbus='clear')

startCsound()

def tr():
    sendOscTrigger(value=1, address='/trig')

def cl():
    sendOscTrigger(value=1, address='/clear')

frame = beginGUI('Infinite Reverb', size=(160,60))
makeButton(frame, label='trig', pos=(10,10), function=tr)
makeButton(frame, label='clear', pos=(80,10), function=cl)
endGUI(frame)\end{verbatim}

\subsection{reverb}

Audio signal is passed through a comb+all-pass reverb.

\bigskip
{\bf SYNTAX}

reverb(input, amplitude=1, duration=None, starttime=0, revtime=2, highdamp=0.5, mix=0.5, pan=0.5, revtimeVar=None, highdampVar=None, mixVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

revtime : Duration, in seconds, of the reverberated sound.

highdamp : Amount of high frequencies diffusion, between 0 and 1. If highdamp is set to 0 then all the frequencies decay with the same speed. If highdamp is 1, high frequencies decay faster than lower ones.

mix : Amplitude of reverberated sound vs input sound at the output.

pan : Position value between 0 and 1.

revtimeVar : Name of the control bus multiplying revtime value.

highdampVar : Name of the control bus multiplying highdamp value.

mixVar : Name of the control bus multiplying mix value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(15)

playSound(sound = 'ounkmaster.aif', out = 'snd')

reverb(input = 'snd', revtime = 3.5, highdamp = .75, mix = .33)

startCsound()
\end{verbatim}

\subsection{waveguideReverb}

Audio signal is passed through a 8 delay line feedback network reverb.

\bigskip
{\bf SYNTAX}

waveguideReverb(input, amplitude=1, duration=None, starttime=0, feedback=0.7, cutoff=10000, mix=0.5, randomize=1, pan=0.5, feedbackVar=None, cutoffVar=None, mixVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





input : Name of the audio input channel.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

feedback : Feedback level, in the range 0 to 1.

cutoff : Cutoff frequency of simple first order lowpass filters in the feedback loop of delay lines, in Hz.

mix : Amplitude of reverberated sound vs input sound at the output.

randomize : Depth of random variation added to delay times, in the range 0 to 10.

pan : Position value between 0 and 1.

feedbackVar : Name of the control bus multiplying feedback value.

cutoffVar : Name of the control bus multiplying cutoff value.

mixVar : Name of the control bus multiplying mix value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.





\section{Sampling}

A set of functions to record audio signals in a temporary buffer and manipulate it.

\subsection{recordAndLoop}

Records audio input and plays it back in a loop.

\bigskip
{\bf SYNTAX}

recordAndLoop(input, trigbus, pitch=1, amplitude=1, starttime=0, duration=None, pan=0.5, nchannels=1, loopduration=1, crossfade=0.05, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip


\section{Sequencer}

A set of functions to build a step sequencer. Every process between function flags 'beginSequencer' and 'endSequencer' will respond to a metronome trigger assigned in 'beginSequencer'.

\subsection{beginSequencer}

Begins the definition of a sequencer.

\bigskip
{\bf SYNTAX}

beginSequencer(input, table, active=1, trigbus=None, trigval=None, mode=0, clockdelay=0, clockdelayVar=None)

\bigskip
\subsection{endSequencer}

Closes the definition of a sequencer.

\bigskip
{\bf SYNTAX}

endSequencer(starttime=0, duration=None)

\bigskip
\subsection{seqParameterTable}

Specifies a parameter table and replaces existing value.

\bigskip
{\bf SYNTAX}

seqParameterTable(parameter, table)

\bigskip
\subsection{sequencerPitchTable}

Specifies a pitch multiplicator table.

\bigskip
{\bf SYNTAX}

sequencerPitchTable(table)

\bigskip


\section{Sources}

A set of functions to generate audio samples. Synthesis, sound playback from disk, soundfonts, etc.  Routing is done by setting the 'out' parameter.

\subsection{bell}

Plays a frequency modulation synthesis sound emulating a tubular bell.

\bigskip
{\bf SYNTAX}

bell(pitch=500, amplitude=0.7, duration=None, starttime=0, pan=0.5, vibratoamp=0.005, vibratofreq=6, index=5, pitchVar=None, amplitudeVar=None, panVar=None, vibratoampVar=None, vibratofreqVar=None, indexVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Fundamental frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

vibratoamp : Vibrato amplitude.

vibratofreq : Vibrato frequency in cycle per seconds.

index : Modulation index. Controls the brightness of the sound.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

vibratoampVar : Name of the control bus multiplying vibratoamp value.

vibratofreqVar : Name of the control bus multiplying vibratofreq value.

indexVar : Name of the control bus multiplying index value.

out = "Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(5)

bell(pitch=150, vibratoamp=.05, index=8)

startCsound()\end{verbatim}

\subsection{freqMod}

Plays a frequency modulation synthesis sound.

\bigskip
{\bf SYNTAX}

freqMod(pitch=500, amplitude=0.7, duration=None, starttime=0, pan=0.5, carrier=1, modulator=0.5, index=5, table='default', envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, carrierVar=None, modulatorVar=None, indexVar=None, out='dac')

\bigskip
\subsection{inputMic}

Retreives sound from a microphone input.

\bigskip
{\bf SYNTAX}

inputMic(amplitude=1, starttime=0, duration=None, channel=1, pan=0.5, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{pinkNoise}

Generates pink noise.

\bigskip
{\bf SYNTAX}

pinkNoise(amplitude=0.7, starttime=0, duration=None, pan=0.5, envelope=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{playSound}

Plays a sound file directly from disk.

\bigskip
{\bf SYNTAX}

playSound(sound='ounkmaster.aif', pitch=1, amplitude=1, loop=False, duration=None, starttime=0, pan=0.5, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





sound : String denoting the source soundfile name. If not a full pathname, the named file is sought in the default sound_path directory.

pitch : Transpose the pitch of input sound by this factor (e.g. 0.5 means one octave lower, 2 is one octave higher, and 1 is the original pitch). Fractional values are allowed.

amplitude : Amplitude (1 is nominal amplitude).

loop : Boolean. If True the file will be played in loop.

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

envelope : Envelope number, returned by genTables functions.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(12)

playSound(sound='ounkmaster.aif', pitch=2, loop=True)

startCsound()\end{verbatim}

\subsection{pluckedString}

Plays the physical model of a string sound.

\bigskip
{\bf SYNTAX}

pluckedString(pitch=100, amplitude=0.7, duration=None, starttime=0, cutoff=6000, pan=0.5, pitchVar=None, amplitudeVar=None, panVar=None, cutoffVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

cutoff : Cutoff frequency of a lowpass filter applied on string model output.

pan : Position value between 0 and 1.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

cutoffVar : Name of the control bus multiplying cutoff value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(20)

pluckedString(pitch=80, cutoff=3000)

startCsound()\end{verbatim}

\subsection{pulsar}

Generates a pulsar synthesis sound.

\bigskip
{\bf SYNTAX}

pulsar(pitch=100, amplitude=0.7, duration=None, starttime=0, tablelen=0.5, pan=0.5, phase=0, wavetable='default', envtable='default', pitchVar=None, amplitudeVar=None, panVar=None, tablelenVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

tablelen : Length, between 0 and 1, of the waveform in fraction of the frequency period. Rest are filled with zeros.

pan : Position value between 0 and 1.

phase : Initial phase of the frequency period.

wavetable : Waveform used to generate the pulsar impulse.

envtable : Envelope applied on the pulsar impulse.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

tablelenVar : Name of the control bus multiplying tablelen value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(30)

setChannels(1)

wav = genWaveform()
env = genWindow()

lfo(bus=['f1','f2','f3'], frequency=[.1,.15,.2], amplitude=.5)
pulsar(pitch=[60,60.25,60.47], tablelen=.5, tablelenVar=['f1','f2','f3'], 
       wavetable=wav, envtable=env, phase=[0,.33,.66])

startCsound()
\end{verbatim}

\subsection{sawtooth}

Plays a sawtooth wave.

\bigskip
{\bf SYNTAX}

sawtooth(pitch=1000, amplitude=0.7, duration=None, starttime=0, pan=0.5, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

envelope : Envelope number, returned by genTables functions.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

# A sawtooth wave with amplitude envelope and pitch variation
env = genAdsr()
lfo(bus='pit', amplitude=.02, frequency=5)
sawtooth(pitch=500, amplitude=.5, envelope=env, pitchVar='pit')
startCsound()
\end{verbatim}

\subsection{sine}

Plays a sine wave.

\bigskip
{\bf SYNTAX}

sine(pitch=1000, amplitude=0.7, duration=None, starttime=0, pan=0.5, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds.  Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

envelope : Envelope number, returned by genTables functions.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

# A sine wave with amplitude envelope and pitch variation
env = genAdsr()
randomi(bus='pit', mini=.95, maxi=1.05)
sine(pitch=500, amplitude=.5, envelope=env, pitchVar='pit')
startCsound()
\end{verbatim}

\subsection{soundfont}

A soundfont player.

\bigskip
{\bf SYNTAX}

soundfont(sf2='piano.SF2', midipitch=48, amplitude=1, duration=None, starttime=0, pan=0.5, channel=1, bank=0, preset=0, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{soundfontMidi}

A soundfont player for use with a midi controller.

\bigskip
{\bf SYNTAX}

soundfontMidi(sf2='piano.SF2', amplitude=1, duration=None, starttime=0, pan=0.5, channel=1, bank=0, preset=0, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{square}

Plays a square wave.

\bigskip
{\bf SYNTAX}

square(pitch=1000, amplitude=0.7, duration=None, starttime=0, pan=0.5, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

envelope : Envelope number, returned by genTables functions.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

# A square wave with amplitude envelope and pitch variation
env = genAdsr()
lfo(bus='pit', amplitude=.02, frequency=5)
square(pitch=500, amplitude=.5, envelope=env, pitchVar='pit')
startCsound()
\end{verbatim}

\subsection{train}

Plays a pulse train synthesis sound.

\bigskip
{\bf SYNTAX}

train(pitch=250, amplitude=0.7, duration=None, starttime=0, pan=0.5, numharms=40, lowharm=0, damp=0.9, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, numharmsVar=None, lowharmVar=None, dampVar=None, out='dac')

\bigskip
\subsection{voiceSynth}

Plays a source-filter synthesized vocal sound.

\bigskip
{\bf SYNTAX}

voiceSynth(pitch=100, amplitude=1, duration=None, starttime=0, pan=0.5, consonant=0, vowel=0, voicetype=0, fadein=0.005, fadeout=0.1, vowelarticulation=1, consonantarticulation=1, pitchglissando=0.02, vowelglissando=0.02, roughness=0.1, formantresonance=1, brilliance=1, glotalresonance=0.5, vibratoamp=0.015, vibratospeed=5.3, voicenumber=None, panVar=None, out='dac')

\bigskip
\subsection{waveform}

Plays a composite waveform (usually generated by genWaveform).

\bigskip
{\bf SYNTAX}

waveform(pitch=1000, amplitude=0.7, duration=None, starttime=0, pan=0.5, envelope=None, table='default', pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





pitch : Frequency in cycles per seconds.

amplitude : Amplitude (1 is nominal amplitude).

duration : Duration of the function performance in seconds. Uses global duration if 'None'.

starttime : Starting time of the function performance in seconds.

pan : Position value between 0 and 1.

table : Number of the waveform table returned by genTables functions.

envelope : Envelope number, returned by genTables functions.

pitchVar : Name of the control bus multiplying pitch value.

amplitudeVar : Name of the control bus multiplying amplitude value.

panVar : Name of the control bus controling panning of the sound, overriding pan value.

out = "Name of the audio output channel. 'dac' means the output is routed to the sound card.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

# An original waveform played with amplitude envelope and pitch variation
env = genAdsr()
wave = genWaveform([1,0,0,.3,0,0,.2,0,0,.1,0,.03,0,.01])
lfo(bus='pit', amplitude=.02, frequency=5)
waveform(pitch=500, amplitude=.5, table=wave, envelope=env, pitchVar='pit')
startCsound()
\end{verbatim}

\subsection{whiteNoise}

Generates white noise.

\bigskip
{\bf SYNTAX}

whiteNoise(amplitude=0.7, starttime=0, duration=None, pan=0.5, envelope=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip


\section{Spatialisation}

A set of functions to place sound in space.

\subsection{pan1to2}

Takes a mono input and distributes it on two channels.

\bigskip
{\bf SYNTAX}

pan1to2(input, starttime=0, duration=None, pan=0.5, panVar=None, out='dac')

\bigskip
\subsection{pan1to4}

Takes a mono input and distributes it on a four channels circle.

\bigskip
{\bf SYNTAX}

pan1to4(input, starttime=0, duration=None, pan=0.5, panVar=None, out='dac')

\bigskip
\subsection{pan1to8}

Takes a mono input and distributes it on a eight channels circle.

\bigskip
{\bf SYNTAX}

pan1to8(input, starttime=0, duration=None, pan=0.5, panVar=None, out='dac')

\bigskip
\subsection{pan2to4}

Takes a stereo input and distributes it on a four channels circle.

\bigskip
{\bf SYNTAX}

pan2to4(input, starttime=0, duration=None, pan=0.5, panVar=None, out='dac')

\bigskip
\subsection{pan2to8}

Takes a stereo input and distributes it on a eight channels circle.

\bigskip
{\bf SYNTAX}

pan2to8(input, starttime=0, duration=None, pan=0.5, panVar=None, out='dac')

\bigskip
\subsection{pan4to8}

Takes a quad input and distributes it on a eight channels circle.

\bigskip
{\bf SYNTAX}

pan4to8(input, starttime=0, duration=None, pan=0.5, panVar=None, out='dac')

\bigskip
\subsection{panner}

Takes an input with an arbitrary number of channels and distributes it on an arbitrary number of channels.

\bigskip
{\bf SYNTAX}

panner(input, starttime=0, duration=None, numinputs=1, numoutputs=2, pan=0.5, offset=0, spread=0.5, panVar=None, spreadVar=None, out='dac')

\bigskip
\subsection{spat1to4}

Takes a mono input and distributes it in an arbitrary four channels space.

\bigskip
{\bf SYNTAX}

spat1to4(input, starttime=0, duration=None, xpos=0.5, ypos=0.5, xposVar=None, yposVar=None, out='dac')

\bigskip


\section{Spectral}

A set of FFT signal procesing functions. Perform FFT analysis on input signals, apply transformations, and perform IFFT to reconstruct audio signals. Routing is done by setting the 'out' parameter.

\subsection{arpegiator}

Arpeggiates the spectral components of a sound. 

\bigskip
{\bf SYNTAX}

arpegiator(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, bin=0.1, attenuation=1, boost=1, binVar=None, attenuationVar=None, boostVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(30)

playSound(out='snd', loop=True)

randomh(bus='rnd', mini=.01, maxi=.3, rate=5)

arpegiator(input='snd', bin=1, binVar='rnd', attenuation=.99, boost=10)

startCsound()
\end{verbatim}

\subsection{blur}

Blurs the sound by smoothing the amplitude and frequency time functions. 

\bigskip
{\bf SYNTAX}

blur(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, blurtime=0.1, blurtimeVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{crossSynth}

Performs cross synthesis.

\bigskip
{\bf SYNTAX}

crossSynth(in1, in2, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, cross=1, crossVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{fftBandpass}

A band pass filter working in the spectral domain. 

\bigskip
{\bf SYNTAX}

fftBandpass(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, lowstart=400, lowend=500, highstart=2000, highend=2500, slope=0, lowstartVar=None, lowendVar=None, highstartVar=None, highendVar=None, slopeVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





slope : specifies the shape of the transitional band. At the default value of zero the shape is linear transition in amplitude. Other values yield and exponential shape. A linear dB shape is obtain when slope is log(10) or about 2.30 .



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
playSound(out='s', loop=True)

lfo(bus='lf', amplitude=.2)

fftBandpass(input='s', slope=2.3, lowstartVar='lf', lowendVar='lf', 
            highstartVar='lf', highendVar='lf')

startCsound()
\end{verbatim}

\subsection{fftBandreject}

A band reject filter working in the spectral domain. 

\bigskip
{\bf SYNTAX}

fftBandreject(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, lowstart=400, lowend=500, highstart=2000, highend=2500, slope=0, lowstartVar=None, lowendVar=None, highstartVar=None, highendVar=None, slopeVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
{\bf PARAMETERS}





slope : specifies the shape of the transitional band. At the default value of zero the shape is linear transition in amplitude. Other values yield and exponential shape. A linear dB shape is obtain when slope is log(10) or about 2.30 .



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
playSound(out='s', loop=True)

lfo(bus='lf', amplitude=.2)

fftBandreject(input='s', slope=2.3, lowstartVar='lf', lowendVar='lf', 
              highstartVar='lf', highendVar='lf')

startCsound()
\end{verbatim}

\subsection{fftBufAdsyn}

Keeps bufferlength seconds of FFT analysis in memory and plays it back at different rate and different tranposition factor. Gives a control on which bin are synthesized.

\bigskip
{\bf SYNTAX}

fftBufAdsyn(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, bufferlength=1, pointerpos=1, transpo=1, numbins=30, firstbin=0, binincr=5, transpoVar=None, pointerposVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{fftBufBlur}

Keeps bufferlength seconds of FFT analysis in memory and plays it back at different rate and control on blur effects. 

\bigskip
{\bf SYNTAX}

fftBufBlur(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, bufferlength=1, pointerpos=1, blur=1, blurVar=None, pointerposVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{fftBufRead}

Keeps bufferlength seconds of FFT analysis in memory and plays it back at different rate and different tranposition factor. 

\bigskip
{\bf SYNTAX}

fftBufRead(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, bufferlength=1, pointerpos=1, transpo=1, keepformant=0, transpoVar=None, pointerposVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(60)

playSound(out='s')

lfo(bus='pt', frequency=.05, amplitude=.5, offset=.5)

fftBufRead(input='s', bufferlength=2, transpo=.5, keepformant=0, pointerposVar='pt')

startCsound()
\end{verbatim}

\subsection{freeze}

Freezes the amplitude and frequency time functions. 

\bigskip
{\bf SYNTAX}

freeze(input, triggerbus, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{maskFilter}

Modify amplitudes using a function table, with dynamic scaling. 

\bigskip
{\bf SYNTAX}

maskFilter(input, table, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, attenuation=1, attenuationVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{reSynth}

Resynthesize a sound using a fast oscillator-bank. 

\bigskip
{\bf SYNTAX}

reSynth(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, numoscs=50, binoffset=0, binincr=5, pitch=1, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{smooth}

Blurs the sound by smoothing the amplitude and frequency time functions. 

\bigskip
{\bf SYNTAX}

smooth(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, smoothamp=0.1, smoothfreq=1, smoothampVar=None, smoothfreqVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{transpose}

Scale the frequency components of a sound. 

\bigskip
{\bf SYNTAX}

transpose(input, amplitude=1, duration=None, starttime=0, pan=0.5, fftsize=1024, overlaps=4, windowsize=2048, transpo=0.5, keepformant=0, transpoVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip


\section{Table process}

A set of functions that perform actions on audio samples stored in a Csound table with 'genSoundTable'. Routing is done by setting the 'out' parameter.

\subsection{flooper}

Loops a sound table with variable loop points.

\bigskip
{\bf SYNTAX}

flooper(table, pitch=1, amplitude=1, starttime=0, duration=None, pan=0.5, startpoint=0, loopmode=0, loopstart=0, loopend=1, crossfade=0.005, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, loopstartVar=None, loopendVar=None, crossfadeVar=None, out='dac')

\bigskip
\subsection{granulator}

Granulates a soundfile stored in a table. Gives control on the pointer rate.

\bigskip
{\bf SYNTAX}

granulator(table, pitch=1, amplitude=1, duration=None, starttime=0, pan=0.5, grainenvelope='default', overlaps=2, grainsize=0.1, pointerrate=1, pitchVar=None, amplitudeVar=None, panVar=None, grainsizeVar=None, pointerrateVar=None, out='dac')

\bigskip
\subsection{granulator2}

Granulates a sound file stored in a table. Gives control on normalized pointer position (0 -> 1).

\bigskip
{\bf SYNTAX}

granulator2(table, pitch=1, amplitude=1, duration=None, starttime=0, pan=0.5, grainenvelope='default', overlaps=2, grainsize=0.1, pointerpos=0, pitchVar=None, amplitudeVar=None, panVar=None, grainsizeVar=None, pointerposVar=None, out='dac')

\bigskip
\subsection{granulator3}

Granulates a sound file stored in a table. Gives control on normalized pointer position (0 -> 1). Grains are send directly to outputs given as a Cound table.

\bigskip
{\bf SYNTAX}

granulator3(table, outstable, pitch=1, amplitude=1, duration=None, starttime=0, grainenvelope='default', overlaps=2, grainsize=0.1, pointerpos=0, pitchVar=None, amplitudeVar=None, grainsizeVar=None, pointerposVar=None)

\bigskip
\subsection{looper}

Loops a sound table.

\bigskip
{\bf SYNTAX}

looper(table, pitch=1, amplitude=1, starttime=0, looplength=1, duration=None, pan=0.5, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{soundTableRead}

Read a sound table once.

\bigskip
{\bf SYNTAX}

soundTableRead(table, pitch=1, amplitude=1, starttime=0, duration=None, pan=0.5, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\subsection{tablesMod}

Ring modulates two tables with index position for each table.

\bigskip
{\bf SYNTAX}

tablesMod(table1, table2, index1=1, index2=1, portamento=0.01, amplitude=1, starttime=0, duration=None, pan=0.5, index1Var=None, index2Var=None, portamentoVar=None, amplitudeVar=None, panVar=None, out='dac')

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import os

setGlobalDuration(60)

setChannels(1)

t1 = genSoundTable(os.getcwd() + '/files/snds/ounkmaster.aif')

lfo(bus=['i1','i2'], frequency=[.15,.08], amplitude=.5, offset=.5)
 
tablesMod(t1, t1, index1Var='i1', index2Var='i2')

startCsound()
\end{verbatim}

\subsection{warper}

Stretches or pitch shifts a sound table.

\bigskip
{\bf SYNTAX}

warper(table, pitch=1, amplitude=1, starttime=0, duration=None, pan=0.5, warp=1, windowsize=4410, windrand=882, overlaps=15, envelope=None, pitchVar=None, amplitudeVar=None, panVar=None, warpVar=None, out='dac')

\bigskip


\section{Trigged Inst}

A set of functions to build a triggered instrument. The instrument can be started and stoped several times by a trigger signal.

\subsection{beginTrigInst}

Begins the definition of a triggered instrument.

\bigskip
{\bf SYNTAX}

beginTrigInst(trigbus=None, trigval=None, release=None)

\bigskip
\subsection{endTrigInst}

Closes the definition of a triggered instrument.

\bigskip
{\bf SYNTAX}

endTrigInst(starttime=0, duration=None)

\bigskip


\chapter{Framework to write Python algorithms}

\section{Algorithmic}

This set of functions are devoted to the creation of algorithmic musical patterns. Some functions create objets with their own methods to control musical behavior. These functions are used in the Python environment to generate, in real-time, the parmeters of events sent to Csound. Must be used with functions in 'Pattern' and 'Python Inst' categories.

\subsection{changeConstant}

Change the constant values used in the logistic or henon equation.

\bigskip
{\bf SYNTAX}

changeConstant(self, constant)

\bigskip
{\bf PARAMETERS}





constant : New constant value to be used in the logistic equation or (a,b) tuple used in the henon equation.



* See logistic or henon page for an example.



\subsection{changeInitial}

Reset the initial value used in the logistic equation to an arbitrary value. henon equation needs a tuple (x,y).

\bigskip
{\bf SYNTAX}

changeInitial(self, initial)

\bigskip
{\bf PARAMETERS}





initial : New initial value to be used in the logistic equation or (x,y) tuple used in the henon equation.



* See logistic or henon page for an example.



\subsection{chord}

Transposes a chord name in a list of pitchs.

\bigskip
{\bf SYNTAX}

chord(name='C', octave=6, format='midi')

\bigskip
{\bf PARAMETERS}





chord : A string pointing to a valid key in the chords dictionary.

octave : Transposition of the chord in number of octave.

format : Chord values format. Valid formats are 'midi', 'hertz' or 'transpo'. The midi pitch 60 is used as the central key for transposition format.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(20)

env = genAdsr()

# MIDI
c = chord('C', octave = 5, format = 'midi')
soundfont(midipitch = c, starttime = 0, duration = 5)

# Hertz
h = chord('C', octave = 5, format = 'hertz')
waveform(pitch = h, amplitude=.3, starttime = 5, duration = 5, envelope = env)

print c, h

startCsound()\end{verbatim}

\subsection{droneAndJump}

Creates a droneAndJump generator objet. Outputs integer values between mini and maxi.

\bigskip
{\bf SYNTAX}

droneAndJump(mini=0, maxi=127)

\bigskip
{\bf PARAMETERS}





mini : Minimum generated value.

maxi : Maximum generated value.



droneAndJump outputs systematically a single note, but sometimes jumps to another note and returns to the first one.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

scl = scale('C')

rnd = droneAndJump(20,40)

time.sleep(1)

def pit():
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next()]
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit)
ti1.start()
ti1.play()



\end{verbatim}

\subsection{drunk}

Creates a drunk generator objet. Outputs integer values between mini and maxi.

\bigskip
{\bf SYNTAX}

drunk(mini=0, maxi=127)

\bigskip
{\bf PARAMETERS}





mini : Minimum generated value.

maxi : Maximum generated value.



drunk performs a random walk generation.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

scl = scale('C')

rnd = drunk(20,40)

time.sleep(1)

def pit():
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next()]
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit)
ti1.start()
ti1.play()



\end{verbatim}

\subsection{getValue}

Returns the current value of a line object.

\bigskip
{\bf SYNTAX}

getValue(self)

\bigskip
{\bf PARAMETERS}





no parameter



* See line page for an example.



\subsection{henon}

The Henon map is a discrete-time dynamical system. It is one of the most studied examples of dynamical systems that exhibit chaotic behavior. 

\bigskip
{\bf SYNTAX}

henon(a=1.4, b=0.3, x=0.1, y=0.1)

\bigskip
{\bf PARAMETERS}





a : Constant value, around 1.4, used in the equation.

b : Constant value, around 0.3, used in the equation.

x : X initial state, in the range 0 to 1, of the system.

y : Y initial state, in the range 0 to 1, of the system.



{\bf METHODS}

obj.next() : return a tuple representing a new point (x, y).

obj.changeConstant((a,b)) : Change the constant values used in the equation. Values are a tuple (a, b)

obj.changeInitial((x,y)) : Reset the initial values used in the equation. Values are a tuple (x, y)



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time, random
setGlobalDuration(-1)

beginPythonInst(1)
soundfont(duration=2, out='snd')
endPythonInst()

lowpass(input='snd', amplitude=2, cutoff=3500)

proc = startCsound()

scl = scale('Cm')

time.sleep(1)

hen = henon()

def pit():
    if (ti1.getBar() % 32) == 0:
        hen.changeInitial((random.uniform(.1,.3), random.uniform(.1,.3)))
        hen.changeConstant((random.choice([1.2,1.3,1.4]), random.choice([.2,.25,.3])))

    x, y = hen.next()

    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[int(mapper(x,-1.5,1.5,12,60))]
    dict['soundfont']['amplitude'] = mapper(y,-2,2,0,1)
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit, [1])
ti1.start()
ti1.play()



\end{verbatim}

\subsection{line}

Creates a line object.

\bigskip
{\bf SYNTAX}

line(start=0, destination=1, duration=None)

\bigskip
{\bf PARAMETERS}





start : Starting value of the line.

destination : Destination value. If a list is given, a breakpoints line will be created.

duration : Duration of a segment of the line. If only one value is supplied for a breakpoints line, each segment will have this duration. If a list is supplied, each destination will have it's own duration.



{\bf METHODS}



obj.start() initializes the thread.

obj.play() starts the line.

obj.play(False) stops the line.

obj.getValue() returns the current value of the line.

obj.stop() kills the thread. 



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(10)

oscReceive(bus='pit', address='/pit', port=9000)
sine(pitch=1, pitchVar='pit')

startCsound()

li = line(start=250, destination=[1000,250], duration=5)
li.start()
li.play()

for i in range(1000):
    val = li.getValue()
    sendOscControl(value=val, address='/pit', port=9000)
    time.sleep(.01)
\end{verbatim}

\subsection{logistic}

The logistic map equation is used to model population growth over time. 

\bigskip
{\bf SYNTAX}

logistic(constant=3.76, initial=0.1)

\bigskip
{\bf PARAMETERS}





constant : Constant value, in the range 0 to 4, used in the equation. When this value is between 0 and 1, result tends to 0. Between 1 and 3, it tends to stabilize on a middle point. Best behaviours are obtained in the range 3 to 4.

initial : Initial state, in the range 0 to 1, of the system. This value has an influence on all the sequence in output.



{\bf METHODS}

obj.next() : return a new value.

obj.changeConstant(const) : Change the constant value used in the equation.

obj.changeInitial(x) : Reset the initial value used in the equation.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time, random
setGlobalDuration(-1)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

scl = scale('C')

time.sleep(1)

# example 1 is chaotic behaviours
# example 2 presents strong patterns and changing values
example = 2

logi = logistic(3.76, .1)
logi2 = logistic(3.5, .1)

def pit():
    x = logi.next()
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[int(mapper(x,0,1,12,60))]
    sendEvent(1, dict, proc)

x1 = x2 = x3 = x4 = 0
count = 0
def pit2():
    global x1, x2, x3, x4, count
    val = logi2.next()
    x = scl[int(mapper(val,0,1,12,60))]
    if x == x4:
        count += 1
    else:
        count = 0
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = x
    sendEvent(1, dict, proc)
 
    x1, x2, x3, x4 = x, x1, x2, x3
    # If a pattern of 4 notes repeats 2 times, we change the constant and initial values
    if count == 8:
        count = 0
        logi2.changeInitial(random.choice([.1,.7,.5]))
        logi2.changeConstant(random.choice([3.5, 3.25, 3]))

if example == 1:
    ti1 = pattern(.125, pit, [1])
    ti1.start()
    ti1.play()
elif example == 2:
    ti1 = pattern(.125, pit2, [1])
    ti1.start()
    ti1.play()


\end{verbatim}

\subsection{loopseg}

Creates a loop segments generator objet. Outputs integer values between mini and maxi.

\bigskip
{\bf SYNTAX}

loopseg(mini=0, maxi=127)

\bigskip
{\bf PARAMETERS}





mini : Minimum generated value.

maxi : Maximum generated value.



loopseg generates cycle of notes and loop them a couple of times before switching.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

scl = scale('C')

rnd = loopseg(20,40)

time.sleep(1)

def pit():
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next()]
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit)
ti1.start()
ti1.play()



\end{verbatim}

\subsection{mapper}

Maps input values inside inmin - inmax range according to output range outmin - outmax.

\bigskip
{\bf SYNTAX}

mapper(input, inmin=0, inmax=127, outmin=0, outmax=1, log=False)

\bigskip
{\bf PARAMETERS}





input : Incoming value (must be in the range inmin et inmax).

inmin : Minimum input value.

inmax : Maximum input value.

outmin : Minimum value of the resultant scale operation.

outmax : Maximum value of the resultant scale operation.

log : If True, scaling will be logarithmic.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import random, time

setGlobalDuration(10)

oscReceive(bus='pit', address='/pit', port=9000)
sine(pitch=1, amplitude=.5, pitchVar='pit')

startCsound()

time.sleep(1)

for i in range(100):
    rnd = random.random() # random values between 0 and 1
    pitch = mapper(rnd, 0, 1, 250, 750, True) # mapped between 250 and 750 logarithmically
    sendOscControl(value=pitch, address='/pit', port=9000)
    time.sleep(.1)
    \end{verbatim}

\subsection{markov}

Creates a markov chain generator objet.

\bigskip
{\bf SYNTAX}

markov(order=2)

\bigskip
{\bf PARAMETERS}





order : Order of the Markov chain. Determines how many past values will be used to build the probability table for the next note.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(-1)

beginPythonInst(1)
soundfont(duration=1)
endPythonInst()

proc = startCsound()

notes = '''67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 72 74 76 74 72 71 69 71 67 66 67 \
	69 62 66 69 72 71 69 71 67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 72 \
	71 69 67 62 67 66 67 71 74 79 74 71 67 71 74 79 62 64 66 69 67 69 72 71 72 69 66 62 66 \
	69 72 71 69 71 67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 72 71 69 67 62 \
	67 66 67 71 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 72 74 76 74 72 71 69 71 67 \
	66 67 69 62 66 69 72 71 69 71 67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 \
	72 71 69 67 62 67 66 67 62 64 66 69 67 69 72 71 72 69 66 62 66 69 72 71 69 71 67 69 71 \
	74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 72 71 69 67 62 67 66 67'''
list = [int(n) for n in notes.split()]

time.sleep(1)

mrk = markov(2)
mrk.mkSetList(list)
mrk.mkStartPlayback()

def pit():
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = mrk.next()+12
    sendEvent(1, dict, proc)

pat = pattern(.125, pit, [1])
pat.start()
pat.play()



\end{verbatim}

\subsection{midiToHertz}

Converts a midi pitch to frequency.

\bigskip
{\bf SYNTAX}

midiToHertz(pitch)

\bigskip
{\bf PARAMETERS}





pitch : midi pitch to be converted in Hertz (cycle per second)



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(9)

scl = [60, 62, 64, 65, 67, 69, 71, 72]
env = genAdsr()

for i in range(len(scl)):
    sine(pitch=midiToHertz(scl[i]), starttime = i, duration = 1, envelope = env)

startCsound()\end{verbatim}

\subsection{midiToTranspo}

Converts a midi pitch to a transposition factor.

\bigskip
{\bf SYNTAX}

midiToTranspo(pitch, centralkey=60)

\bigskip
{\bf PARAMETERS}





pitch : midi pitch to be converted in transposition factor

centralkey : midi pitch used as nominal value (midiToTranspo(60) returns 1.)



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

base_pitch = 100
chd = [60, 64, 67]
env = genAdsr()

pinkNoise(amplitude = .02, envelope = env, duration = 7, out = 'noise')
for i in range(3):
    tr = midiToTranspo(chd[i])
    resonator(input = 'noise', pitch = base_pitch * tr, feedback = .995)

startCsound()\end{verbatim}

\subsection{mkChangeOrder}

Changes the order of the markov chain.

\bigskip
{\bf SYNTAX}

mkChangeOrder(self, value)

\bigskip
{\bf PARAMETERS}





order : Order of the Markov chain. Determines how many past values will be used to build the probability table for the next note.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(-1)

beginPythonInst(1)
soundfont(duration=1)
endPythonInst()

proc = startCsound()

notes = '''67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 72 74 76 74 72 71 69 71 67 66 67 \
	69 62 66 69 72 71 69 71 67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 72 \
	71 69 67 62 67 66 67 71 74 79 74 71 67 71 74 79 62 64 66 69 67 69 72 71 72 69 66 62 66 \
	69 72 71 69 71 67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 72 71 69 67 62 \
	67 66 67 71 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 72 74 76 74 72 71 69 71 67 \
	66 67 69 62 66 69 72 71 69 71 67 69 71 74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 \
	72 71 69 67 62 67 66 67 62 64 66 69 67 69 72 71 72 69 66 62 66 69 72 71 69 71 67 69 71 \
	74 72 72 76 74 74 79 78 79 74 71 67 69 71 64 74 72 71 69 67 62 67 66 67'''
list = [int(n) for n in notes.split()]

time.sleep(1)

mrk = markov(10)
mrk.mkSetList(list)
mrk.mkStartPlayback()

flag = True
def pit():
    global flag
    if (pat.getBar() % 32) == 0:
        if flag:
            order = 10
            flag = False
        else:
            order = 1
            flag = True
        print flag
        mrk.mkChangeOrder(order) 
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = mrk.next()+12
    sendEvent(1, dict, proc)

pat = pattern(.125, pit, [1])
pat.start()
pat.play()



\end{verbatim}

\subsection{mkRecord}

Appends a new value to a sequence to be analyzed.

\bigskip
{\bf SYNTAX}

mkRecord(self, value)

\bigskip
{\bf PARAMETERS}





value : In record mode, the value is added to the list used for the generation.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(-1)

beginPythonInst(1)
soundfont(duration=1)
endPythonInst()

proc = startCsound()

time.sleep(1)

scl = scale('Cm')
rnd = loopseg(25,55)

mrk = markov(3)
mrk.mkStartRecord()

# generates and records 30 seconds of random pitches...
def randomPitches():
    pitch = scl[rnd.next(4)]
    mrk.mkRecord(pitch)
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = pitch
    sendEvent(1, dict, proc)

# and play them back in a markov chain
def markovPlayback():
    pitch = mrk.next()
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = pitch
    sendEvent(1, dict, proc)

pat = pattern(.125, randomPitches, [1])
pat.start()
pat.play()

time.sleep(30)

pat.play(False)

time.sleep(2)

mrk.mkStartPlayback()
pat2 = pattern(.125, markovPlayback, [1])
pat2.start()
pat2.play()


\end{verbatim}

\subsection{mkSetList}

Takes a list as a sequence to be analyzed.

\bigskip
{\bf SYNTAX}

mkSetList(self, list)

\bigskip
{\bf PARAMETERS}





list : New sequence used to determine picked up values.



* See markov page for an example.

\subsection{mkStartPlayback}

Sets up a markov chain for playback.

\bigskip
{\bf SYNTAX}

mkStartPlayback(self)

\bigskip
{\bf PARAMETERS}





no parameter



* See markov page for an example.



\subsection{mkStartRecord}

Initializes a markov chain to record a new sequence.

\bigskip
{\bf SYNTAX}

mkStartRecord(self)

\bigskip
{\bf PARAMETERS}





no parameter



* See mkRecord for an example.



\subsection{next}

Method to call a new value from a generator objet.

\bigskip
{\bf SYNTAX}

next(self, maxStepSize=-2)

\bigskip
{\bf PARAMETERS}





maxStepSize : Maximum step size for each call. If negative, repetition are not permitted.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time, random
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

scl = scale('C')

rnd = drunk(20,40)

time.sleep(1)

steps = [0, 1, -1, -8]

def pit():
    step = steps[(ti1.getBar() / 16) % 4] # wrap around steps list (change every 16 notes) 
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next(step)]
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit)
ti1.start()
ti1.play()



\end{verbatim}

\subsection{oneCall}

Calls a function after a delay time.

\bigskip
{\bf SYNTAX}

oneCall(delay, function)

\bigskip
{\bf PARAMETERS}





delay : Delay time, in seconds, before calling the function.

function : Function to be called.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time, random
setGlobalDuration(20)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

time.sleep(2)

# let the function pit call itself over and over...
active = True

def pit():
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = random.randint(36,60)
    sendEvent(1, dict, proc)
    if active:
        oneCall(.25, pit)

# ... breaks the loop when the script is stoped
def onStop():
    global active
    active = False

pit()

\end{verbatim}

\subsection{repeater}

Creates a repeater generator objet. Outputs integer values between mini and maxi.

\bigskip
{\bf SYNTAX}

repeater(mini=0, maxi=127)

\bigskip
{\bf PARAMETERS}





mini : Minimum generated value.

maxi : Maximum generated value.



repeater outputs many times a note before switching to another one.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=2)
endPythonInst()

proc = startCsound()

scl = scale('C')

rnd = repeater(20,40)

time.sleep(1)

def pit():
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next()]
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit)
ti1.start()
ti1.play()



\end{verbatim}

\subsection{scale}

Transposes a scale name in a list of pitchs.

\bigskip
{\bf SYNTAX}

scale(name='C', format='midi')

\bigskip
{\bf PARAMETERS}





chord : A string pointing to a valid key in the scales dictionary.

octave : Transposition of the chord in number of octave.

format : Scale values format. Valid formats are 'midi', 'hertz' or 'transpo'. The midi pitch 60 is used as the central key for transposition format.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import random

setGlobalDuration(6)

env = genAdsr(release = .7)

sclMidi = scale('C', 'midi')
sclHertz = scale('C', 'hertz')

# MIDI
for i in range(16):
    soundfont(midipitch = sclMidi[random.randint(24,48)], starttime = i * .25, duration = 2)
    waveform(pitch = sclHertz[random.randint(24,48)], starttime = i * .25, duration = 2, 
             amplitude = .1, envelope = env)

startCsound()\end{verbatim}

\subsection{semitoneToTranspo}

Converts a semitone value to a transposition factor.

\bigskip
{\bf SYNTAX}

semitoneToTranspo(semitone)

\bigskip
{\bf PARAMETERS}





semitone : semitone value to be converted in transposition factor





\section{GUI}

A set of functions to create a graphical interface for the control of sound parameters.

\subsection{beginGUI}

Begins the definition of a graphical user interface.

\bigskip
{\bf SYNTAX}

beginGUI(name='Ounk GUI', size=(260,300))

\bigskip
\subsection{endGUI}

Closes and displays the graphical user interface.

\bigskip
{\bf SYNTAX}

endGUI(frame)

\bigskip
\subsection{makeButton}

Creates a button.

\bigskip
{\bf SYNTAX}

makeButton(frame=None, label='Button', pos=(0,0), function=None)

\bigskip
\subsection{makeCircleSlider}

Creates a circle slider window. Function will receive a list of (x,y) position values.

\bigskip
{\bf SYNTAX}

makeCircleSlider(frame=None, label='Circle Slider', pos=(0,0), size=(200,200), mini=0, maxi=1, function=None)

\bigskip
\subsection{makeMenu}

Creates a menu.

\bigskip
{\bf SYNTAX}

makeMenu(frame=None, label='Menu', pos=(0,0), choicelist=['1', '2', '3', '4'], function=None)

\bigskip
\subsection{makeMultiSlider}

Creates a multi slider window. Function will receive a list of slider values.

\bigskip
{\bf SYNTAX}

makeMultiSlider(frame=None, init=0, mini=0, maxi=1, sliders=16, valtype='float', label='MultiSlider', pos=(0,0), size=(200,200), orientation='vertical', function=None)

\bigskip
\subsection{makeRangeSlider}

Creates a range slider window. Function will receive a list of slider's two values.

\bigskip
{\bf SYNTAX}

makeRangeSlider(frame=None, init=[0, 0.5], mini=0, maxi=1, valtype='float', label='RangeSlider', pos=(0,0), size=(200,20), function=None)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(-1)

oscReceive(bus=['min', 'max'], address=['/min','/max'], port=8000)
randomh(bus='pit', mini=1, maxi=1, rate=8, miniVar='min', maxiVar='max')
sine(pitch=1, pitchVar='pit')

startCsound()

def ranger(list):
    sendOscControl(list[0], address='/min', port=8000)
    sendOscControl(list[1], address='/max', port=8000)

f = beginGUI(size=(250,100))
makeRangeSlider(f, [400,600], mini=300, maxi=1500, valtype='float', size=(200,20), function=ranger)
endGUI(f)\end{verbatim}

\subsection{makeSlider}

Creates a slider.

\bigskip
{\bf SYNTAX}

makeSlider(frame=None, label='Slider', init=0, mini=0, maxi=100, pos=(0,0), size=(250,-1), orientation='horizontal', function=None)

\bigskip
\subsection{makeSpin}

Creates a spin controller.

\bigskip
{\bf SYNTAX}

makeSpin(frame=None, label='Spin Ctrl', init=0, mini=0, maxi=100, pos=(0,0), size=(100,-1), function=None)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(-1)

oscReceive(bus='pit', address='/pit', port=9000)
sine(pitch=100, pitchVar='pit')

startCsound()

def spinner(evt):
    print sp.GetValue()
    sendOscControl(sp.GetValue(), address='/pit', port=9000)

frame = beginGUI(size=(150,150))
sp = makeSpin(frame, init=1, mini=1, maxi=10, pos=(20,20), function=spinner)
endGUI(frame)\end{verbatim}

\subsection{makeToggle}

Creates a Toggle button.

\bigskip
{\bf SYNTAX}

makeToggle(frame=None, label='Toggle', pos=(0,0), function=None)

\bigskip
\subsection{makeXYSlider}

Creates an XY slider window. Function will receive a list of (x,y) position values.

\bigskip
{\bf SYNTAX}

makeXYSlider(frame=None, label='XY Slider', pos=(0,0), size=(200,200), mini=0, maxi=1, function=None)

\bigskip


\section{Patterns}

A pattern objet is a Python timer that follow a rhythm pattern to call a user-defined function. This function can be used to send events to a Python Inst.

\subsection{changePattern}

Assigns a new pattern to a pattern objet.

\bigskip
{\bf SYNTAX}

changePattern(self, pattern)

\bigskip
{\bf PARAMETERS}





pattern : List of ticks duration.        



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import random

setGlobalDuration(10)

patChoice = [[1,1,1,1], [1,1,2], [2,2], [4]]
def printTime():
    if ti1.getBeat() == 1 and (ti1.getBar() % 4) == 0:
        ti1.changePattern(random.choice(patChoice))
    print ti1.getBeat()

ti1 = pattern(0.125, printTime, [1,1,1,1])
ti1.start()
ti1.play()

startCsound()

\end{verbatim}

\subsection{changeTime}

Changes the time interval of a pattern objet.

\bigskip
{\bf SYNTAX}

changeTime(self, time)

\bigskip
{\bf PARAMETERS}





time : Time interval, in seconds, between clocker calls.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import random

setGlobalDuration(10)

def printTime():
    if ti1.getBeat() == 1 and (ti1.getBar() % 4) == 0:
        ti1.changeTime(random.randint(100,200) * 0.001)
    print ti1.getTime()

ti1 = pattern(0.125, printTime, [1,1,1,1])
ti1.start()
ti1.play()

startCsound()

\end{verbatim}

\subsection{getBar}

Return the current bar of the pattern.

\bigskip
{\bf SYNTAX}

getBar(self)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

def printBar():
    print ti1.getBar()

ti1 = pattern(0.125, printBar, [1,1,2])
ti1.start()
ti1.play()

startCsound()

\end{verbatim}

\subsection{getBeat}

Returns the current beat of the pattern.

\bigskip
{\bf SYNTAX}

getBeat(self)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

def printBeat():
    print ti1.getBeat()

ti1 = pattern(0.125, printBeat, [1,1,2])
ti1.start()
ti1.play()

startCsound()

\end{verbatim}

\subsection{getTime}

Returns the current time of the pattern.

\bigskip
{\bf SYNTAX}

getTime(self)

\bigskip
\bigskip
{\bf EXAMPLE}
\begin{verbatim}
setGlobalDuration(10)

def printTime():
    print ti1.getTime()

ti1 = pattern(0.125, printTime, [1,1,2])
ti1.start()
ti1.play()

startCsound()

\end{verbatim}

\subsection{pattern}

Creates an independent clocker for scheduling events with sendEvent.

\bigskip
{\bf SYNTAX}

pattern(time=0.125, function=None, pattern=[1])

\bigskip
{\bf PARAMETERS}





time : Delay time, in seconds, between each clock step.

function : Function to be called on each time of the pattern.

pattern : List of beat durations, in number of clock steps.

arg1 -> arg10 : Up to 10 arguments can be passed to function. These arguments are sent on each call.



{\bf METHODS}



obj.start() : Clockers are managed in separated threads. This method must be called first to activate the threads.

obj.play() : Starts the clock.

obj.play(False) : Stops the clock.

obj.getTime() : Returns the current time, in seconds, since the start of the pattern.

obj.getBeat() : Returns the current beat of the pattern.

obj.getBar() : Return the current bar since the start of the pattern.

obj.changeTime(x) : Changes the time interval of the pattern objet.

obj.changePattern(list) : Assigns a new pattern to the pattern objet.

obj.stop() Kills the thread.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import random, time
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=4)
endPythonInst()

proc = startCsound()

scl = scale('Em')

rnd = loopseg(25,35)

time.sleep(2)
patterns = [[4,2,2,1,1], [3,2,2,3], [2,1,1,1,1,2,1,1], [4,1,1,1,1,1,1]]

def pit():
    if ti1.getBeat() == 1 and (ti1.getBar() % 4) == 0:
        ti1.changePattern(random.choice(patterns))
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next()]
    dict['soundfont']['pan'] = random.randint(0,7)*0.125
    sendEvent(1, dict, proc)

ti1 = pattern(.125, pit, [3,3,2,2])
ti1.start()
ti1.play()


\end{verbatim}

\subsection{regenerate}

Regenerate a new algorithmic rhythm sequence based on new weights.

\bigskip
{\bf SYNTAX}

regenerate(self, size=16, weight1=90, weight2=60, weight3=20)

\bigskip
{\bf PARAMETERS}





size : Length, in number of steps, of the new generated sequence.

weight1 : Percentage chance of primary beats to be chosen.

weight2 : Percentage chance of secondary beats to be chosen.

weight3 : Percentage chance of weak beats to be chosen.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
from random import randint
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=4)
endPythonInst()

proc = startCsound()

time.sleep(2)

flag = True
def pit(amp):
    global flag
    if flag and (ti1.getBar() % 4) == 0:
        ti1.regenerate(16, randint(60,90), randint(40,70), randint(30,60))
        flag = False
    if (ti1.getBar() % 4 == 1):
        flag = True
    dict = {'soundfont': {}}
    dict['soundfont']['amplitude'] = amp
    sendEvent(1, dict, proc)

ti1 = rhythmPattern(.1, pit, 16, 90, 60, 20)
ti1.start()
ti1.play()


\end{verbatim}

\subsection{rhythmPattern}

Creates an algorithmic rhythm pattern for scheduling events with sendEvent.

\bigskip
{\bf SYNTAX}

rhythmPattern(time=0.125, function=None, size=16, weight1=90, weight2=60, weight3=20)

\bigskip
{\bf PARAMETERS}





time : Delay time, in seconds, between each clock step.

function : Function to be called on each time of the pattern. Function will receive an amplitude value.

size : Length of the bar, in number of steps.

weight1 : Percentage chance of primary beats to be chosen.

weight2 : Percentage chance of secondary beats to be chosen.

weight3 : Percentage chance of weak beats to be chosen.



{\bf METHODS}



obj.start() : Clockers are managed in separated threads. This method must be called first to activate the threads.

obj.play() : Starts the clock.

obj.play(False) : Stops the clock.

obj.getTime() : Returns the current time, in seconds, since the start of the pattern.

obj.getBeat() : Returns the current beat of the pattern.

obj.getBar() : Return the current bar since the start of the pattern.

obj.changeTime(x) : Changes the time interval of the pattern objet.

obj.changePattern(size, weigth1, weigth2, weigth3) : Regenerate a new algorithmic rhythm sequence based on new weights.

obj.stop() Kills the thread.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
from random import randint
setGlobalDuration(30)

beginPythonInst(1)
soundfont(duration=4)
endPythonInst()

proc = startCsound()

scl = scale('Em')

rnd = loopseg(25,35)

time.sleep(2)

def pit(amp):
    if ti1.getBeat() == 1 and (ti1.getBar() % 4) == 0:
        ti1.regenerate(16, randint(60,90), randint(40,70), randint(30,60))
    dict = {'soundfont': {}}
    dict['soundfont']['midipitch'] = scl[rnd.next()]
    dict['soundfont']['pan'] = random.randint(0,7)*0.125
    dict['soundfont']['amplitude'] = amp
    sendEvent(1, dict, proc)

ti1 = rhythmPattern(.1, pit, 16, 90, 60, 20)
ti1.start()
ti1.play()


\end{verbatim}

\subsection{sendCsoundMsg}

Sends a message to csound stdin. Can be used to modify a ftable.

\bigskip
{\bf SYNTAX}

sendCsoundMsg(string, process=1)

\bigskip
{\bf PARAMETERS}





string : Csound message as a string (Usually a score line).

process : Ounk process number returned by startCsound(). This value is used to send the message to the intended Csound instance.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
from random import choice
setGlobalDuration(30)

env = genAdsr()
w = genWaveform()

waveform(pitch=250, envelope=env, table=w, amplitude=.5)

proc = startCsound()

time.sleep(1)

def newWave():
    myStr = "f" + str(w) + " 0 8192 10 " + " ".join([str(choice([0,0,0,0,.2,.3,.5,.7,1])) for i in range(10)]) + "\n"
    print myStr
    sendCsoundMsg(myStr, proc)

ti1 = pattern(.5, newWave, [1])
ti1.start()
ti1.play()


\end{verbatim}

\subsection{sendEvent}

Sends an event to a python instrument.

\bigskip
{\bf SYNTAX}

sendEvent(voice=1, dict=None, process=1, post=False)

\bigskip
{\bf PARAMETERS}





voice : Voice number of the Python instrument intended to receive the event.

dict : A dictionary specifying new parameter values for an event. If a parameter is given in the Python instrument and is not given in the dictionary, the value in the Python instrument will be used.

process : Ounk process number, returned by startCsound. This is used to avoid interference between different Python instrument inside different already running scripts.



- Dictionary syntax -



The keys are function names (as a string) associated with a dictionary of parameters. Parameters are keys (also as a string) associated with the desired value.

To control a Python instrument with a sound player and a lowpass filter, dict should look like this:



dict = \{\}

dict['playSound'] = \{\}

dict['lowpass'] = \{\}

dict['playSound']['pitch'] = .5

dict['playSound']['loop'] = True

dict['lowpass']['cutoff'] = 2500



sendEvent(voice=1, dict=dict, process=1)



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time

setGlobalDuration(30)

beginPythonInst(voice=1)
playSound(duration=8, out='snd')
bandpass(input='snd', duration=5, out='rev')
endPythonInst()

reverb(input='rev', revtime=1.5, highdamp=.7, mix=.25)

proc = startCsound()

time.sleep(1)
dict = {'playSound': {'pitch': .5, 'loop': False, 'pan': 0}, 
        'bandpass': {'cutoff': 500, 'bandwidth': 200}}
sendEvent(1, dict, proc)

time.sleep(5)
dict = {'playSound': {'pitch': .75, 'loop': False, 'pan': .25}, 
        'bandpass': {'cutoff': 500, 'bandwidth': 200}}
sendEvent(1, dict, proc)

time.sleep(5)
dict = {'playSound': {'pitch': 1, 'loop': False, 'pan': .5}, 
        'bandpass': {'cutoff': 1000, 'bandwidth': 200}}
sendEvent(1, dict, proc)

time.sleep(5)
dict = {'playSound': {'pitch': 1.5, 'loop': True, 'pan': .75}, 
        'bandpass': {'cutoff': 1500, 'bandwidth': 400}}
sendEvent(1, dict, proc)

time.sleep(5)
dict = {'playSound': {'pitch': 2, 'loop': True, 'pan': 1}, 
        'bandpass': {'cutoff': 1000, 'bandwidth': 100}}
sendEvent(1, dict, proc)\end{verbatim}

\subsection{sendOscControl}

Sends a value from python to an osc port.

\bigskip
{\bf SYNTAX}

sendOscControl(value, address, port=8000, host='127.0.0.1')

\bigskip
{\bf PARAMETERS}





value : Numerical value to send on an OSC port.

address : A string that is the destination address. This takes the form of a file name with directories. 

port : The port on which to listen.

host : A string that is the intended host computer domain name. The default value ('127.0.0.1') is the current computer.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
from random import uniform
setGlobalDuration(30)

env = genAdsr()

oscReceive(bus='pit', address='/pit', port=9000, portamento=.025)

sine(pitch=1, pitchVar='pit', envelope=env, amplitude=.5)

proc = startCsound()

time.sleep(1)

def pit():
    sendOscControl(value = uniform(200,800), address='/pit', port=9000)

ti1 = pattern(.5, pit, [1])
ti1.start()
ti1.play()


\end{verbatim}

\subsection{sendOscTrigger}

Sends a value from python to an OSC port and immediatly after sends -1 to the same port.

\bigskip
{\bf SYNTAX}

sendOscTrigger(value, address, port=8000, host='127.0.0.1')

\bigskip
{\bf PARAMETERS}





value : Numerical value to be triggered.

address : A string that is the destination address. This takes the form of a file name with directories. 

port : The port on which to listen.

host : A string that is the intended host computer domain name. The default value ('127.0.0.1') is the current computer.



\bigskip
{\bf EXAMPLE}
\begin{verbatim}
import time
from random import uniform
setGlobalDuration(30)

env = genAdsr()

oscReceive(bus='trig', address='/trig', port=9000)

trigRandom(bus='pit', trigbus='trig', mini=200, maxi=800)

sine(pitch=1, pitchVar='pit', envelope=env, amplitude=.5)

proc = startCsound()

time.sleep(1)

def pit():
    sendOscTrigger(value = 1, address='/trig', port=9000)

ti1 = pattern(.5, pit, [1])
ti1.start()
ti1.play()


\end{verbatim}



\end{document}
